Hi; this pullreq contains some minor bug fixes, and also

the txt-to-rST document conversions I did. The latter are not

strictly speaking bugfixes but I think for rc2 they're OK. Let

me know if you'd rather I respin this without them.

The following changes since commit 0f397dcfecc9211d12c2c720c01eb32f0eaa7d23:

Merge tag 'pull-nbd-2024-08-08' of https://repo.or.cz/qemu/ericb into staging (2024-08-09 08:40:37 +1000)

https://git.linaro.org/people/pmaydell/qemu-arm.git tags/pull-target-arm-20240809

for you to fetch changes up to 77100e100d76a568800e19ee20c7e9255053b84a:

arm/virt: place power button pin number on a define (2024-08-09 17:37:56 +0100)

* Fix BTI versus CF_PCREL

* include: Fix typo in name of MAKE_IDENTFIER macro

* docs: Various txt-to-rST conversions

* add support for PMUv3 64-bit PMCCNTR in AArch32 mode

* hw/core/ptimer: fix timer zero period condition for freq > 1GHz

* arm/virt: place power button pin number on a define

Alex Richardson (1):

target/arm: add support for PMUv3 64-bit PMCCNTR in AArch32 mode

Eric Blake (1):

docs: Typo fix in live disk backup

Jianzhou Yue (1):

hw/core/ptimer: fix timer zero period condition for freq > 1GHz

Mauro Carvalho Chehab (1):

arm/virt: place power button pin number on a define

Peter Maydell (6):

include: Fix typo in name of MAKE_IDENTFIER macro

docs/specs/rocker.txt: Convert to rST

docs/interop/nbd.txt: Convert to rST

docs/interop/parallels.txt: Convert to rST

docs/interop/prl-xml.txt: Convert to rST

docs/interop/prl-xml.rst: Fix minor grammar nits

Richard Henderson (1):

target/arm: Fix BTI versus CF_PCREL

MAINTAINERS | 7 +-

docs/interop/index.rst | 3 +

docs/interop/live-block-operations.rst | 4 +-

docs/interop/nbd.rst | 89 ++++++++++++

docs/interop/nbd.txt | 72 ----------

docs/interop/{parallels.txt => parallels.rst} | 108 ++++++++-------

docs/interop/prl-xml.rst | 192 ++++++++++++++++++++++++++

docs/interop/prl-xml.txt | 158 ---------------------

docs/specs/index.rst | 1 +

docs/specs/{rocker.txt => rocker.rst} | 181 ++++++++++++------------

include/hw/arm/virt.h | 3 +

include/qapi/qmp/qobject.h | 2 +-

include/qemu/atomic.h | 2 +-

include/qemu/compiler.h | 2 +-

include/qemu/osdep.h | 6 +-

target/arm/tcg/helper-a64.h | 3 +

target/arm/tcg/translate.h | 2 -

hw/arm/virt-acpi-build.c | 6 +-

hw/arm/virt.c | 7 +-

hw/core/ptimer.c | 4 +-

target/arm/helper.c | 6 +

target/arm/tcg/helper-a64.c | 39 ++++++

target/arm/tcg/translate-a64.c | 64 ++-------

tests/unit/ptimer-test.c | 33 +++++

24 files changed, 553 insertions(+), 441 deletions(-)

create mode 100644 docs/interop/nbd.rst

delete mode 100644 docs/interop/nbd.txt

rename docs/interop/{parallels.txt => parallels.rst} (72%)

create mode 100644 docs/interop/prl-xml.rst

delete mode 100644 docs/interop/prl-xml.txt

rename docs/specs/{rocker.txt => rocker.rst} (91%)

From: Eric Blake <eblake@redhat.com>

Add in the missing space in the section header.

Fixes: 1084159b31 ("qapi: deprecate drive-backup", v6.2.0)

Signed-off-by: Eric Blake <eblake@redhat.com>

docs/interop/live-block-operations.rst | 4 ++--

diff --git a/docs/interop/live-block-operations.rst b/docs/interop/live-block-operations.rst

--- a/docs/interop/live-block-operations.rst

+++ b/docs/interop/live-block-operations.rst

@@ -XXX,XX +XXX,XX @@ Shutdown the guest, by issuing the ``quit`` QMP command::

}

-Live disk backup --- ``blockdev-backup`` and the deprecated``drive-backup``

----------------------------------------------------------------------------

+Live disk backup --- ``blockdev-backup`` and the deprecated ``drive-backup``

+----------------------------------------------------------------------------

The ``blockdev-backup`` (and the deprecated ``drive-backup``) allows

you to create a point-in-time snapshot.

Fix some minor grammar nits in the prl-xml documentation.

docs/interop/prl-xml.rst | 73 +++++++++++++++++++++-------------------

1 file changed, 39 insertions(+), 34 deletions(-)

diff --git a/docs/interop/prl-xml.rst b/docs/interop/prl-xml.rst

--- a/docs/interop/prl-xml.rst

+++ b/docs/interop/prl-xml.rst

@@ -XXX,XX +XXX,XX @@ Parallels Disk Format

See the COPYING file in the top-level directory.

This specification contains minimal information about Parallels Disk Format,

-which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server

-and Parallels Desktop are able to add some unspecified nodes to xml and use

+which is enough to properly work with QEMU. Nevertheless, Parallels Cloud Server

+and Parallels Desktop are able to add some unspecified nodes to the xml and use

them, but they are for internal work and don't affect functionality. Also it

-uses auxiliary xml ``Snapshot.xml``, which allows to store optional snapshot

-information, but it doesn't influence open/read/write functionality. QEMU and

-other software should not use fields not covered in this document and

-``Snapshot.xml`` file and must leave them as is.

+uses auxiliary xml ``Snapshot.xml``, which allows storage of optional snapshot

+information, but this doesn't influence open/read/write functionality. QEMU and

+other software should not use fields not covered in this document or the

+``Snapshot.xml`` file, and must leave them as is.

-Parallels disk consists of two parts: the set of snapshots and the disk

+A Parallels disk consists of two parts: the set of snapshots and the disk

descriptor file, which stores information about all files and snapshots.

Definitions

@@ -XXX,XX +XXX,XX @@ Definitions

Snapshot

a record of the contents captured at a particular time, capable

- of storing current state. A snapshot has UUID and parent UUID.

+ of storing current state. A snapshot has a UUID and a parent UUID.

Snapshot image

an overlay representing the difference between this

@@ -XXX,XX +XXX,XX @@ Overlay

an image storing the different sectors between two captured states.

Root image

- snapshot image with no parent, the root of snapshot tree.

+ a snapshot image with no parent, the root of the snapshot tree.

Storage

the backing storage for a subset of the virtual disk. When

there is more than one storage in a Parallels disk then that

is referred to as a split image. In this case every storage

- covers specific address space area of the disk and has its

+ covers a specific address space area of the disk and has its

particular root image. Split images are not considered here

and are not supported. Each storage consists of disk

parameters and a list of images. The list of images always

@@ -XXX,XX +XXX,XX @@ Storage

Description file

``DiskDescriptor.xml`` stores information about disk parameters,

- snapshots, storages.

+ snapshots, and storages.

Top Snapshot

The overlay between actual state and some previous snapshot.

@@ -XXX,XX +XXX,XX @@ Description file

All information is placed in a single XML element

``Parallels_disk_image``.

-The element has only one attribute ``Version``, that must be ``1.0``.

+The element has only one attribute, ``Version``, which must be ``1.0``.

-Schema of ``DiskDescriptor.xml``::

+The schema of ``DiskDescriptor.xml``::

<Parallels_disk_image Version="1.0">

<Disk_Parameters>

@@ -XXX,XX +XXX,XX @@ The ``Disk_Parameters`` element MUST contain the following child elements:

* ``Heads`` - number of the disk heads.

* ``Sectors`` - number of the disk sectors per cylinder

(sector size is 512 bytes)

- Limitation: Product of the ``Heads``, ``Sectors`` and ``Cylinders``

+ Limitation: The product of the ``Heads``, ``Sectors`` and ``Cylinders``

values MUST be equal to the value of the Disk_size parameter.

* ``Padding`` - must be 0. Parallels Cloud Server and Parallels Desktop may

- use padding set to 1, however this case is not covered

- by this spec, QEMU and other software should not open

+ use padding set to 1; however this case is not covered

+ by this specification. QEMU and other software should not open

such disks and should not create them.

``StorageData`` element

@@ -XXX,XX +XXX,XX @@ as shown below::

</Storage>

</StorageData>

-A ``Storage`` element has following child elements:

+A ``Storage`` element has the following child elements:

* ``Start`` - start sector of the storage, in case of non split storage

equals to 0.

* ``End`` - number of sector following the last sector, in case of non

split storage equals to ``Disk_size``.

* ``Blocksize`` - storage cluster size, number of sectors per one cluster.

- Cluster size for each "Compressed" (see below) image in

- parallels disk must be equal to this field. Note: cluster

- size for Parallels Expandable Image is in ``tracks`` field of

+ The cluster size for each "Compressed" (see below) image in

+ a parallels disk must be equal to this field. Note: the cluster

+ size for a Parallels Expandable Image is in the ``tracks`` field of

its header (see :doc:`parallels`).

* Several ``Image`` child elements.

-Each ``Image`` element has following child elements:

+Each ``Image`` element has the following child elements:

* ``GUID`` - image identifier, UUID in curly brackets.

For instance, ``{12345678-9abc-def1-2345-6789abcdef12}.``

@@ -XXX,XX +XXX,XX @@ Each ``Image`` element has following child elements:

* ``Plain`` for raw files.

* ``Compressed`` for expanding disks.

-* ``File`` - path to image file. Path can be relative to

+* ``File`` - path to image file. The path can be relative to

``DiskDescriptor.xml`` or absolute.

``Snapshots`` element

@@ -XXX,XX +XXX,XX @@ Each ``Shot`` element contains the following child elements:

* ``GUID`` - an image GUID.

* ``ParentGUID`` - GUID of the image of the parent snapshot.

-The software may traverse snapshots from child to parent using ``<ParentGUID>``

-field as reference. ``ParentGUID`` of root snapshot is

-``{00000000-0000-0000-0000-000000000000}``. There should be only one root

-snapshot. Top snapshot could be described via two ways: via ``TopGUID`` child

-element of the ``Snapshots`` element or via predefined GUID

+The software may traverse snapshots from child to parent using the

+``<ParentGUID>`` field as reference. The ``ParentGUID`` of the root

+snapshot is ``{00000000-0000-0000-0000-000000000000}``.

+There should be only one root snapshot.

+

+The Top snapshot could be

+described via two ways: via the ``TopGUID`` child

+element of the ``Snapshots`` element, or via the predefined GUID

``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined,

-predefined GUID is interpreted as usual GUID. All snapshot images

-(except Top Snapshot) should be

-opened read-only. There is another predefined GUID,

+the predefined GUID is interpreted as a normal GUID. All snapshot images

+(except the Top Snapshot) should be

+opened read-only.

+

+There is another predefined GUID,

``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by

-original and some third-party software for backup, QEMU and other

-software may operate with images with ``GUID = BackupID`` as usual,

-however, it is not recommended to use this

-GUID for new disks. Top snapshot cannot have this GUID.

+original and some third-party software for backup. QEMU and other

+software may operate with images with ``GUID = BackupID`` as usual.

+However, it is not recommended to use this

+GUID for new disks. The Top snapshot cannot have this GUID.

Convert prl-xml.txt to rST format.

MAINTAINERS | 1 +

docs/interop/index.rst | 1 +

docs/interop/prl-xml.rst | 187 +++++++++++++++++++++++++++++++++++++++

docs/interop/prl-xml.txt | 158 ---------------------------------

4 files changed, 189 insertions(+), 158 deletions(-)

create mode 100644 docs/interop/prl-xml.rst

delete mode 100644 docs/interop/prl-xml.txt

diff --git a/MAINTAINERS b/MAINTAINERS

--- a/MAINTAINERS

+++ b/MAINTAINERS

@@ -XXX,XX +XXX,XX @@ S: Supported

F: block/parallels.c

F: block/parallels-ext.c

F: docs/interop/parallels.rst

+F: docs/interop/prl-xml.rst

T: git https://src.openvz.org/scm/~den/qemu.git parallels

qed

diff --git a/docs/interop/index.rst b/docs/interop/index.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/interop/index.rst

+++ b/docs/interop/index.rst

@@ -XXX,XX +XXX,XX @@ are useful for making QEMU interoperate with other software.

live-block-operations

nbd

parallels

+ prl-xml

pr-helper

qmp-spec

qemu-ga

diff --git a/docs/interop/prl-xml.rst b/docs/interop/prl-xml.rst

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null

+++ b/docs/interop/prl-xml.rst

@@ -XXX,XX +XXX,XX @@

+Parallels Disk Format

+=====================

+

+..

+ Copyright (c) 2015-2017, Virtuozzo, Inc.

+ Authors:

+ 2015 Denis Lunev <den@openvz.org>

+ 2015 Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>

+ 2016-2017 Klim Kireev <klim.kireev@virtuozzo.com>

+ 2016-2017 Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>

+

+ This work is licensed under the terms of the GNU GPL, version 2 or later.

+ See the COPYING file in the top-level directory.

+

+This specification contains minimal information about Parallels Disk Format,

+which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server

+and Parallels Desktop are able to add some unspecified nodes to xml and use

+them, but they are for internal work and don't affect functionality. Also it

+uses auxiliary xml ``Snapshot.xml``, which allows to store optional snapshot

+information, but it doesn't influence open/read/write functionality. QEMU and

+other software should not use fields not covered in this document and

+``Snapshot.xml`` file and must leave them as is.

+

+Parallels disk consists of two parts: the set of snapshots and the disk

+descriptor file, which stores information about all files and snapshots.

+

+Definitions

+-----------

+

+Snapshot

+ a record of the contents captured at a particular time, capable

+ of storing current state. A snapshot has UUID and parent UUID.

+

+Snapshot image

+ an overlay representing the difference between this

+ snapshot and some earlier snapshot.

+

+Overlay

+ an image storing the different sectors between two captured states.

+

+Root image

+ snapshot image with no parent, the root of snapshot tree.

+

+Storage

+ the backing storage for a subset of the virtual disk. When

+ there is more than one storage in a Parallels disk then that

+ is referred to as a split image. In this case every storage

+ covers specific address space area of the disk and has its

+ particular root image. Split images are not considered here

+ and are not supported. Each storage consists of disk

+ parameters and a list of images. The list of images always

+ contains a root image and may also contain overlays. The

+ root image can be an expandable Parallels image file or

+ plain. Overlays must be expandable.

+

+Description file

+ ``DiskDescriptor.xml`` stores information about disk parameters,

+ snapshots, storages.

+

+Top Snapshot

+ The overlay between actual state and some previous snapshot.

+ It is not a snapshot in the classical sense because it

+ serves as the active image that the guest writes to.

+

+Sector

+ a 512-byte data chunk.

+

+Description file

+----------------

+

+All information is placed in a single XML element

+``Parallels_disk_image``.

+The element has only one attribute ``Version``, that must be ``1.0``.

+

+Schema of ``DiskDescriptor.xml``::

+

+ <Parallels_disk_image Version="1.0">

+ <Disk_Parameters>

+ ...

+ </Disk_Parameters>

+ <StorageData>

+ ...

+ </StorageData>

+ <Snapshots>

+ ...

+ </Snapshots>

+ </Parallels_disk_image>

+

+``Disk_Parameters`` element

+^^^^^^^^^^^^^^^^^^^^^^^^^^^

+

+The ``Disk_Parameters`` element describes the physical layout of the

+virtual disk and some general settings.

+

+The ``Disk_Parameters`` element MUST contain the following child elements:

+

+* ``Disk_size`` - number of sectors in the disk,

+ desired size of the disk.

+* ``Cylinders`` - number of the disk cylinders.

+* ``Heads`` - number of the disk heads.

+* ``Sectors`` - number of the disk sectors per cylinder

+ (sector size is 512 bytes)

+ Limitation: Product of the ``Heads``, ``Sectors`` and ``Cylinders``

+ values MUST be equal to the value of the Disk_size parameter.

+* ``Padding`` - must be 0. Parallels Cloud Server and Parallels Desktop may

+ use padding set to 1, however this case is not covered

+ by this spec, QEMU and other software should not open

+ such disks and should not create them.

+

+``StorageData`` element

+^^^^^^^^^^^^^^^^^^^^^^^

+

+This element of the file describes the root image and all snapshot images.

+

+The ``StorageData`` element consists of the ``Storage`` child element,

+as shown below::

+

+ <StorageData>

+ <Storage>

+ ...

+ </Storage>

+ </StorageData>

+

+A ``Storage`` element has following child elements:

+

+* ``Start`` - start sector of the storage, in case of non split storage

+ equals to 0.

+* ``End`` - number of sector following the last sector, in case of non

+ split storage equals to ``Disk_size``.

+* ``Blocksize`` - storage cluster size, number of sectors per one cluster.

+ Cluster size for each "Compressed" (see below) image in

+ parallels disk must be equal to this field. Note: cluster

+ size for Parallels Expandable Image is in ``tracks`` field of

+ its header (see :doc:`parallels`).

+* Several ``Image`` child elements.

+

+Each ``Image`` element has following child elements:

+

+* ``GUID`` - image identifier, UUID in curly brackets.

+ For instance, ``{12345678-9abc-def1-2345-6789abcdef12}.``

+ The GUID is used by the Snapshots element to reference images

+ (see below)

+* ``Type`` - image type of the element. It can be:

+

+ * ``Plain`` for raw files.

+ * ``Compressed`` for expanding disks.

+

+* ``File`` - path to image file. Path can be relative to

+ ``DiskDescriptor.xml`` or absolute.

+

+``Snapshots`` element

+^^^^^^^^^^^^^^^^^^^^^

+

+The ``Snapshots`` element describes the snapshot relations with the snapshot tree.

+

+The element contains the set of ``Shot`` child elements, as shown below::

+

+ <Snapshots>

+ <TopGUID> ... </TopGUID> /* Optional child element */

+ <Shot>

+ ...

+ </Shot>

+ <Shot>

+ ...

+ </Shot>

+ ...

+ </Snapshots>

+

+Each ``Shot`` element contains the following child elements:

+

+* ``GUID`` - an image GUID.

+* ``ParentGUID`` - GUID of the image of the parent snapshot.

+

+The software may traverse snapshots from child to parent using ``<ParentGUID>``

+field as reference. ``ParentGUID`` of root snapshot is

+``{00000000-0000-0000-0000-000000000000}``. There should be only one root

+snapshot. Top snapshot could be described via two ways: via ``TopGUID`` child

+element of the ``Snapshots`` element or via predefined GUID

+``{5fbaabe3-6958-40ff-92a7-860e329aab41}``. If ``TopGUID`` is defined,

+predefined GUID is interpreted as usual GUID. All snapshot images

+(except Top Snapshot) should be

+opened read-only. There is another predefined GUID,

+``BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}``, which is used by

+original and some third-party software for backup, QEMU and other

+software may operate with images with ``GUID = BackupID`` as usual,

+however, it is not recommended to use this

+GUID for new disks. Top snapshot cannot have this GUID.

diff --git a/docs/interop/prl-xml.txt b/docs/interop/prl-xml.txt

deleted file mode 100644

index XXXXXXX..XXXXXXX

--- a/docs/interop/prl-xml.txt

+++ /dev/null

@@ -XXX,XX +XXX,XX @@

-= License =

-

-Copyright (c) 2015-2017, Virtuozzo, Inc.

-Authors:

- 2015 Denis Lunev <den@openvz.org>

- 2015 Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>

- 2016-2017 Klim Kireev <klim.kireev@virtuozzo.com>

- 2016-2017 Edgar Kaziakhmedov <edgar.kaziakhmedov@virtuozzo.com>

-

-This work is licensed under the terms of the GNU GPL, version 2 or later.

-See the COPYING file in the top-level directory.

-

-This specification contains minimal information about Parallels Disk Format,

-which is enough to proper work with QEMU. Nevertheless, Parallels Cloud Server

-and Parallels Desktop are able to add some unspecified nodes to xml and use

-them, but they are for internal work and don't affect functionality. Also it

-uses auxiliary xml "Snapshot.xml", which allows to store optional snapshot

-information, but it doesn't influence open/read/write functionality. QEMU and

-other software should not use fields not covered in this document and

-Snapshot.xml file and must leave them as is.

-

-= Parallels Disk Format =

-

-Parallels disk consists of two parts: the set of snapshots and the disk

-descriptor file, which stores information about all files and snapshots.

-

-== Definitions ==

- Snapshot a record of the contents captured at a particular time,

- capable of storing current state. A snapshot has UUID and

- parent UUID.

-

- Snapshot image an overlay representing the difference between this

- snapshot and some earlier snapshot.

-

- Overlay an image storing the different sectors between two captured

- states.

-

- Root image snapshot image with no parent, the root of snapshot tree.

-

- Storage the backing storage for a subset of the virtual disk. When

- there is more than one storage in a Parallels disk then that

- is referred to as a split image. In this case every storage

- covers specific address space area of the disk and has its

- particular root image. Split images are not considered here

- and are not supported. Each storage consists of disk

- parameters and a list of images. The list of images always

- contains a root image and may also contain overlays. The

- root image can be an expandable Parallels image file or

- plain. Overlays must be expandable.

-

- Description DiskDescriptor.xml stores information about disk parameters,

- file snapshots, storages.

-

- Top The overlay between actual state and some previous snapshot.

- Snapshot It is not a snapshot in the classical sense because it

- serves as the active image that the guest writes to.

-

- Sector a 512-byte data chunk.

-

-== Description file ==

-All information is placed in a single XML element Parallels_disk_image.

-The element has only one attribute "Version", that must be 1.0.

-Schema of DiskDescriptor.xml:

-

-<Parallels_disk_image Version="1.0">

- <Disk_Parameters>

- ...

- </Disk_Parameters>

- <StorageData>

- ...

- </StorageData>

- <Snapshots>

- ...

- </Snapshots>

-</Parallels_disk_image>

-

-== Disk_Parameters element ==

-The Disk_Parameters element describes the physical layout of the virtual disk

-and some general settings.

-

-The Disk_Parameters element MUST contain the following child elements:

- * Disk_size - number of sectors in the disk,

- desired size of the disk.

- * Cylinders - number of the disk cylinders.

- * Heads - number of the disk heads.

- * Sectors - number of the disk sectors per cylinder

- (sector size is 512 bytes)

- Limitation: Product of the Heads, Sectors and Cylinders

- values MUST be equal to the value of the Disk_size parameter.

- * Padding - must be 0. Parallels Cloud Server and Parallels Desktop may

- use padding set to 1, however this case is not covered

- by this spec, QEMU and other software should not open

- such disks and should not create them.

-

-== StorageData element ==

-This element of the file describes the root image and all snapshot images.

-

-The StorageData element consists of the Storage child element, as shown below:

-<StorageData>

- <Storage>

- ...

- </Storage>

-</StorageData>

-

-A Storage element has following child elements:

- * Start - start sector of the storage, in case of non split storage

- equals to 0.

- * End - number of sector following the last sector, in case of non

- split storage equals to Disk_size.

- * Blocksize - storage cluster size, number of sectors per one cluster.

- Cluster size for each "Compressed" (see below) image in

- parallels disk must be equal to this field. Note: cluster

- size for Parallels Expandable Image is in 'tracks' field of

- its header (see docs/interop/parallels.txt).

- * Several Image child elements.

-

-Each Image element has following child elements:

- * GUID - image identifier, UUID in curly brackets.

- For instance, {12345678-9abc-def1-2345-6789abcdef12}.

- The GUID is used by the Snapshots element to reference images

- (see below)

- * Type - image type of the element. It can be:

- "Plain" for raw files.

- "Compressed" for expanding disks.

- * File - path to image file. Path can be relative to DiskDescriptor.xml or

- absolute.

-

-== Snapshots element ==

-The Snapshots element describes the snapshot relations with the snapshot tree.

-

-The element contains the set of Shot child elements, as shown below:

-<Snapshots>

- <TopGUID> ... </TopGUID> /* Optional child element */

- <Shot>

- ...

- </Shot>

- <Shot>

- ...

- </Shot>

- ...

-</Snapshots>

-

-Each Shot element contains the following child elements:

- * GUID - an image GUID.

- * ParentGUID - GUID of the image of the parent snapshot.

-

-The software may traverse snapshots from child to parent using <ParentGUID>

-field as reference. ParentGUID of root snapshot is

-{00000000-0000-0000-0000-000000000000}. There should be only one root

-snapshot. Top snapshot could be described via two ways: via TopGUID child

-element of the Snapshots element or via predefined GUID

-{5fbaabe3-6958-40ff-92a7-860e329aab41}. If TopGUID is defined, predefined GUID is

-interpreted as usual GUID. All snapshot images (except Top Snapshot) should be

-opened read-only. There is another predefined GUID,

-BackupID = {704718e1-2314-44c8-9087-d78ed36b0f4e}, which is used by original and

-some third-party software for backup, QEMU and other software may operate with

-images with GUID = BackupID as usual, however, it is not recommended to use this

-GUID for new disks. Top snapshot cannot have this GUID.

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Having magic numbers inside the code is not a good idea, as it

is error-prone. So, instead, create a macro with the number

definition.

Link: https://lore.kernel.org/qemu-devel/CAFEAcA-PYnZ-32MRX+PgvzhnoAV80zBKMYg61j2f=oHaGfwSsg@mail.gmail.com/

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Reviewed-by: Igor Mammedov <imammedo@redhat.com>

Message-id: ef0e7f5fca6cd94eda415ecee670c3028c671b74.1723121692.git.mchehab+huawei@kernel.org

Suggested-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Reviewed-by: Igor Mammedov <imammedo@redhat.com>

include/hw/arm/virt.h | 3 +++

hw/arm/virt-acpi-build.c | 6 +++---

hw/arm/virt.c | 7 ++++---

3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/include/hw/arm/virt.h b/include/hw/arm/virt.h

--- a/include/hw/arm/virt.h

+++ b/include/hw/arm/virt.h

@@ -XXX,XX +XXX,XX @@

/* See Linux kernel arch/arm64/include/asm/pvclock-abi.h */

#define PVTIME_SIZE_PER_CPU 64

+/* GPIO pins */

+#define GPIO_PIN_POWER_BUTTON 3

+

enum {

VIRT_FLASH,

VIRT_MEM,

diff --git a/hw/arm/virt-acpi-build.c b/hw/arm/virt-acpi-build.c

index XXXXXXX..XXXXXXX 100644

--- a/hw/arm/virt-acpi-build.c

+++ b/hw/arm/virt-acpi-build.c

@@ -XXX,XX +XXX,XX @@ static void acpi_dsdt_add_gpio(Aml *scope, const MemMapEntry *gpio_memmap,

aml_append(dev, aml_name_decl("_CRS", crs));

Aml *aei = aml_resource_template();

- /* Pin 3 for power button */

- const uint32_t pin_list[1] = {3};

+

+ const uint32_t pin = GPIO_PIN_POWER_BUTTON;

aml_append(aei, aml_gpio_int(AML_CONSUMER, AML_EDGE, AML_ACTIVE_HIGH,

- AML_EXCLUSIVE, AML_PULL_UP, 0, pin_list, 1,

+ AML_EXCLUSIVE, AML_PULL_UP, 0, &pin, 1,

"GPO0", NULL, 0));

aml_append(dev, aml_name_decl("_AEI", aei));

diff --git a/hw/arm/virt.c b/hw/arm/virt.c

index XXXXXXX..XXXXXXX 100644

--- a/hw/arm/virt.c

+++ b/hw/arm/virt.c

@@ -XXX,XX +XXX,XX @@ static void virt_powerdown_req(Notifier *n, void *opaque)

if (s->acpi_dev) {

acpi_send_event(s->acpi_dev, ACPI_POWER_DOWN_STATUS);

} else {

- /* use gpio Pin 3 for power button event */

+ /* use gpio Pin for power button event */

qemu_set_irq(qdev_get_gpio_in(gpio_key_dev, 0), 1);

}

}

@@ -XXX,XX +XXX,XX @@ static void create_gpio_keys(char *fdt, DeviceState *pl061_dev,

uint32_t phandle)

{

gpio_key_dev = sysbus_create_simple("gpio-key", -1,

- qdev_get_gpio_in(pl061_dev, 3));

+ qdev_get_gpio_in(pl061_dev,

+ GPIO_PIN_POWER_BUTTON));

qemu_fdt_add_subnode(fdt, "/gpio-keys");

qemu_fdt_setprop_string(fdt, "/gpio-keys", "compatible", "gpio-keys");

@@ -XXX,XX +XXX,XX @@ static void create_gpio_keys(char *fdt, DeviceState *pl061_dev,

qemu_fdt_setprop_cell(fdt, "/gpio-keys/poweroff", "linux,code",

KEY_POWER);

qemu_fdt_setprop_cells(fdt, "/gpio-keys/poweroff",

- "gpios", phandle, 3, 0);

+ "gpios", phandle, GPIO_PIN_POWER_BUTTON, 0);

}

#define SECURE_GPIO_POWEROFF 0

Convert the rocker.txt specification document to rST format. We make

extensive use of the :: marker to introduce a literal block for all

the tables and ASCII art, rather than trying to convert the tables to

rST table syntax. This produces a valid rST document without needing

a huge diff.

MAINTAINERS | 2 +-

docs/specs/index.rst | 1 +

docs/specs/{rocker.txt => rocker.rst} | 181 +++++++++++++-------------

3 files changed, 93 insertions(+), 91 deletions(-)

rename docs/specs/{rocker.txt => rocker.rst} (91%)

diff --git a/MAINTAINERS b/MAINTAINERS

--- a/MAINTAINERS

+++ b/MAINTAINERS

@@ -XXX,XX +XXX,XX @@ S: Maintained

F: hw/net/rocker/

F: qapi/rocker.json

F: tests/rocker/

-F: docs/specs/rocker.txt

+F: docs/specs/rocker.rst

e1000x

M: Dmitry Fleytman <dmitry.fleytman@gmail.com>

diff --git a/docs/specs/index.rst b/docs/specs/index.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/specs/index.rst

+++ b/docs/specs/index.rst

@@ -XXX,XX +XXX,XX @@ guest hardware that is specific to QEMU.

vmcoreinfo

vmgenid

rapl-msr

+ rocker

diff --git a/docs/specs/rocker.txt b/docs/specs/rocker.rst

similarity index 91%

rename from docs/specs/rocker.txt

rename to docs/specs/rocker.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/specs/rocker.txt

+++ b/docs/specs/rocker.rst

@@ -XXX,XX +XXX,XX @@

Rocker Network Switch Register Programming Guide

-Copyright (c) Scott Feldman <sfeldma@gmail.com>

-Copyright (c) Neil Horman <nhorman@tuxdriver.com>

-Version 0.11, 12/29/2014

+************************************************

-LICENSE

-=======

+..

+ Copyright (c) Scott Feldman <sfeldma@gmail.com>

+ Copyright (c) Neil Horman <nhorman@tuxdriver.com>

+ Version 0.11, 12/29/2014

-This program is free software; you can redistribute it and/or modify

-it under the terms of the GNU General Public License as published by

-the Free Software Foundation; either version 2 of the License, or

-(at your option) any later version.

+ This program is free software; you can redistribute it and/or modify

+ it under the terms of the GNU General Public License as published by

+ the Free Software Foundation; either version 2 of the License, or

+ (at your option) any later version.

-This program is distributed in the hope that it will be useful,

-but WITHOUT ANY WARRANTY; without even the implied warranty of

-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

-GNU General Public License for more details.

+ This program is distributed in the hope that it will be useful,

+ but WITHOUT ANY WARRANTY; without even the implied warranty of

+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

+ GNU General Public License for more details.

-SECTION 1: Introduction

-=======================

+Introduction

+============

Overview

--------

@@ -XXX,XX +XXX,XX @@ software.

Notations and Conventions

-------------------------

-o In register descriptions, [n:m] indicates a range from bit n to bit m,

-inclusive.

-o Use of leading 0x indicates a hexadecimal number.

-o Use of leading 0b indicates a binary number.

-o The use of RSVD or Reserved indicates that a bit or field is reserved for

-future use.

-o Field width is in bytes, unless otherwise noted.

-o Register are (R) read-only, (R/W) read/write, (W) write-only, or (COR) clear

-on read

-o TLV values in network-byte-order are designated with (N).

+* In register descriptions, [n:m] indicates a range from bit n to bit m,

+ inclusive.

+* Use of leading 0x indicates a hexadecimal number.

+* Use of leading 0b indicates a binary number.

+* The use of RSVD or Reserved indicates that a bit or field is reserved for

+ future use.

+* Field width is in bytes, unless otherwise noted.

+* Register are (R) read-only, (R/W) read/write, (W) write-only, or (COR) clear

+ on read

+* TLV values in network-byte-order are designated with (N).

-SECTION 2: PCI Configuration Registers

-======================================

+PCI Configuration Registers

+===========================

PCI Configuration Space

-----------------------

-Each switch instance registers as a PCI device with PCI configuration space:

+Each switch instance registers as a PCI device with PCI configuration space::

    offset    width    description        value

    ---------------------------------------------

@@ -XXX,XX +XXX,XX @@ Each switch instance registers as a PCI device with PCI configuration space:

    0x41    1    Retry count

    0x42    2    Reserved

+ * Assigned by sub-system implementation

-* Assigned by sub-system implementation

-

-SECTION 3: Memory-Mapped Register Space

-=======================================

+Memory-Mapped Register Space

+============================

There are two memory-mapped BARs. BAR0 maps device register space and is

0x2000 in size. BAR1 maps MSI-X vector and PBA tables and is also 0x2000 in

@@ -XXX,XX +XXX,XX @@ byte registers with one 4-byte access, and 8 byte registers with either two

4-byte accesses or a single 8-byte access. In the case of two 4-byte accesses,

access must be lower and then upper 4-bytes, in that order.

-BAR0 device register space is organized as follows:

+BAR0 device register space is organized as follows::

    offset        description

    ------------------------------------------------------

@@ -XXX,XX +XXX,XX @@ Reads to reserved registers read back as 0.

No fancy stuff like write-combining is enabled on any of the registers.

-BAR1 MSI-X register space is organized as follows:

+BAR1 MSI-X register space is organized as follows::

    offset        description

    ------------------------------------------------------

@@ -XXX,XX +XXX,XX @@ BAR1 MSI-X register space is organized as follows:

    0x1000-0x1fff    MSI-X PBA table

-SECTION 4: Interrupts, DMA, and Endianness

-==========================================

+Interrupts, DMA, and Endianness

+===============================

PCI Interrupts

--------------

@@ -XXX,XX +XXX,XX @@ PCI Interrupts

The device supports only MSI-X interrupts. BAR1 memory-mapped region contains

the MSI-X vector and PBA tables, with support for up to 256 MSI-X vectors.

-The vector assignment is:

+The vector assignment is::

    vector        description

    -----------------------------------------------------

@@ -XXX,XX +XXX,XX @@ The vector assignment is:

             Tx vector is even

             Rx vector is odd

-A MSI-X vector table entry is 16 bytes:

+A MSI-X vector table entry is 16 bytes::

    field        offset    width    description

    -------------------------------------------------------------

@@ -XXX,XX +XXX,XX @@ ring, and hardware will set this bit when the descriptor is complete.

Descriptor ring sizes must be a power of 2 and range from 2 to 64K entries.

Descriptor rings' base address must be 8-byte aligned. Descriptors must be

packed within ring. Each descriptor in each ring must also be aligned on an 8

-byte boundary. Each descriptor ring will have these registers:

+byte boundary. Each descriptor ring will have these registers::

    DMA_DESC_xxx_BASE_ADDR, offset 0x1000 + (x * 32), 64-bit, (R/W)

    DMA_DESC_xxx_SIZE, offset 0x1008 + (x * 32), 32-bit, (R/W)

@@ -XXX,XX +XXX,XX @@ byte boundary. Each descriptor ring will have these registers:

    DMA_DESC_xxx_CREDITS, offset 0x1018 + (x * 32), 32-bit, (R/W)

    DMA_DESC_xxx_RSVD1, offset 0x101c + (x * 32), 32-bit, (R/W)

-Where x is descriptor ring index:

+Where x is descriptor ring index::

    index        ring

    --------------------

@@ -XXX,XX +XXX,XX @@ written past TAIL. To do so would wrap the ring. An empty ring is when HEAD

== TAIL. A full ring is when HEAD is one position behind TAIL. Both HEAD and

TAIL increment and modulo wrap at the ring size.

-CTRL register bits:

+CTRL register bits::

    bit    name        description

    ------------------------------------------------------------------------

    [0]    CTRL_RESET    Reset the descriptor ring

    [1:31]    Reserved

-All descriptor types share some common fields:

+All descriptor types share some common fields::

    field            width    description

    -------------------------------------------------------------------

@@ -XXX,XX +XXX,XX @@ filled in by the switch. Likewise, the switch will ignore unknown fields

filled in by software.

Descriptor payload buffer is 8-byte aligned and TLVs are 8-byte aligned. The

-value within a TLV is also 8-byte aligned. The (packed, 8 byte) TLV header is:

+value within a TLV is also 8-byte aligned. The (packed, 8 byte) TLV header is::

    field    width    description

    -----------------------------

@@ -XXX,XX +XXX,XX @@ The alignment requirements for descriptors and TLVs are to avoid unaligned

access exceptions in software. Note that the payload for each TLV is also

8 byte aligned.

-Figure 1 shows an example descriptor buffer with two TLVs.

+Figure 1 shows an example descriptor buffer with two TLVs::

<------- 8 bytes ------->

@@ -XXX,XX +XXX,XX @@ network packet data. All non-network-packet TLV multi-byte values will be LE.

TLV values in network-byte-order are designated with (N).

-SECTION 5: Test Registers

-=========================

+Test Registers

+==============

Rocker has several test registers to support troubleshooting register access,

-interrupt generation, and DMA operations:

+interrupt generation, and DMA operations::

    TEST_REG, offset 0x0010, 32-bit (R/W)

    TEST_REG64, offset 0x0018, 64-bit (R/W)

@@ -XXX,XX +XXX,XX @@ for that vector.

To test basic DMA operations, allocate a DMA-able host buffer and put the

buffer address into TEST_DMA_ADDR and size into TEST_DMA_SIZE. Then, write to

-TEST_DMA_CTRL to manipulate the buffer contents. TEST_DMA_CTRL operations are:

+TEST_DMA_CTRL to manipulate the buffer contents. TEST_DMA_CTRL operations are::

    operation        value    description

    -----------------------------------------------------------

@@ -XXX,XX +XXX,XX @@ issue exists. In particular, buffers that start on odd-8-byte boundary and/or

span multiple PAGE sizes should be tested.

-SECTION 6: Ports

-================

+Ports

+=====

Physical and Logical Ports

------------------------------------

The switch supports up to 62 physical (front-panel) ports. Register

-PORT_PHYS_COUNT returns the actual number of physical ports available:

+PORT_PHYS_COUNT returns the actual number of physical ports available::

    PORT_PHYS_COUNT, offset 0x0304, 32-bit, (R)

@@ -XXX,XX +XXX,XX @@ Front-panel ports and logical tunnel ports are mapped into a single 32-bit port

space. A special CPU port is assigned port 0. The front-panel ports are

mapped to ports 1-62. A special loopback port is assigned port 63. Logical

tunnel ports are assigned ports 0x0001000-0x0001ffff.

-To summarize the port assignments:

+To summarize the port assignments::

    port            mapping

    -------------------------------------------------------

@@ -XXX,XX +XXX,XX @@ set/get the mode for front-panel ports, see port settings, below.

Port Settings

-------------

-Link status for all front-panel ports is available via PORT_PHYS_LINK_STATUS:

+Link status for all front-panel ports is available via PORT_PHYS_LINK_STATUS::

    PORT_PHYS_LINK_STATUS, offset 0x0310, 64-bit, (R)

    Value is port bitmap. Bits 0 and 63 always read 0. Bits 1-62

    read 1 for link UP and 0 for link DOWN for respective front-panel ports.

-Other properties for front-panel ports are available via DMA CMD descriptors:

+Other properties for front-panel ports are available via DMA CMD descriptors::

    Get PORT_SETTINGS descriptor:

@@ -XXX,XX +XXX,XX @@ Port Enable

-----------

Front-panel ports are initially disabled, which means port ingress and egress

-packets will be dropped. To enable or disable a port, use PORT_PHYS_ENABLE:

+packets will be dropped. To enable or disable a port, use PORT_PHYS_ENABLE::

    PORT_PHYS_ENABLE: offset 0x0318, 64-bit, (R/W)

@@ -XXX,XX +XXX,XX @@ packets will be dropped. To enable or disable a port, use PORT_PHYS_ENABLE:

    Default is 0.

-SECTION 7: Switch Control

-=========================

+Switch Control

+==============

This section covers switch-wide register settings.

Control

-------

-This register is used for low level control of the switch.

+This register is used for low level control of the switch::

    CONTROL: offset 0x0300, 32-bit, (W)

@@ -XXX,XX +XXX,XX @@ Switch ID

---------

The switch has a SWITCH_ID to be used by software to uniquely identify the

-switch:

+switch::

    SWITCH_ID: offset 0x0320, 64-bit, (R)

    Value is opaque to switch software and no special encoding is implied.

-SECTION 8: Events

-=================

+Events

+======

Non-I/O asynchronous events from the device are notified to the host using the

-event ring. The TLV structure for events is:

+event ring. The TLV structure for events is::

    field        width    description

    ---------------------------------------------------

@@ -XXX,XX +XXX,XX @@ event ring. The TLV structure for events is:

Link Changed Event

------------------

-When link status changes on a physical port, this event is generated.

+When link status changes on a physical port, this event is generated::

    field        width    description

    ---------------------------------------------------

@@ -XXX,XX +XXX,XX @@ driver should install to the device the MAC/VLAN on the port into the bridge

table. Once installed, the MAC/VLAN is known on the port and this event will

no longer be generated.

+::

+

    field        width    description

    ---------------------------------------------------

    INFO        <nest>

@@ -XXX,XX +XXX,XX @@ no longer be generated.

     VLAN        2    VLAN ID

-SECTION 9: CPU Packet Processing

-================================

+CPU Packet Processing

+=====================

Ingress packets directed to the host CPU for further processing are delivered

in the DMA RX ring. Likewise, host CPU originating packets destined to egress

@@ -XXX,XX +XXX,XX @@ software that Tx is complete and software resources (e.g. skb) backing packet

can be released.

Figure 2 shows an example 3-fragment packet queued with one Tx descriptor. A

-TLV is used for each packet fragment.

+TLV is used for each packet fragment::

     pkt frag 1

     +–––––––+ +–+

@@ -XXX,XX +XXX,XX @@ TLV is used for each packet fragment.

                fig 2.

-The TLVs for Tx descriptor buffer are:

+The TLVs for Tx descriptor buffer are::

    field            width    description

    ---------------------------------------------------------------------

@@ -XXX,XX +XXX,XX @@ The TLVs for Tx descriptor buffer are:

     TX_FRAG_ADDR    8    DMA address of packet fragment

     TX_FRAG_LEN        2    Packet fragment length

-Possible status return codes in descriptor on completion are:

+Possible status return codes in descriptor on completion are::

    DESC_COMP_ERR    reason

    --------------------------------------------------------------------

@@ -XXX,XX +XXX,XX @@ worst-case packet size. A single Rx descriptor will contain the entire Rx

packet data in one RX_FRAG. Other Rx TLVs describe and hardware offloads

performed on the packet, such as checksum validation.

-The TLVs for Rx descriptor buffer are:

+The TLVs for Rx descriptor buffer are::

    field        width    description

    ---------------------------------------------------

@@ -XXX,XX +XXX,XX @@ The TLVs for Rx descriptor buffer are:

Offload forward RX_FLAG indicates the device has already forwarded the packet

so the host CPU should not also forward the packet.

-Possible status return codes in descriptor on completion are:

+Possible status return codes in descriptor on completion are::

    DESC_COMP_ERR    reason

    --------------------------------------------------------------------

@@ -XXX,XX +XXX,XX @@ Possible status return codes in descriptor on completion are:

            packet data TLV and other TLVs.

-SECTION 10: OF-DPA Mode

-======================

+OF-DPA Mode

+===========

OF-DPA mode allows the switch to offload flow packet processing functions to

hardware. An OpenFlow controller would communicate with an OpenFlow agent

installed on the switch. The OpenFlow agent would (directly or indirectly)

communicate with the Rocker switch driver, which in turn would program switch

-hardware with flow functionality, as defined in OF-DPA. The block diagram is:

+hardware with flow functionality, as defined in OF-DPA. The block diagram is::

        +–––––––––––––––----–––+

        | OF |

@@ -XXX,XX +XXX,XX @@ OF-DPA Flow Table Interface

There are commands to add, modify, delete, and get stats of flow table entries.

The commands are issued using the DMA CMD descriptor ring. The following

-commands are defined:

+commands are defined::

    CMD_ADD:        add an entry to flow table

    CMD_MOD:        modify an entry in flow table

    CMD_DEL:        delete an entry from flow table

    CMD_GET_STATS:        get stats for flow entry

-TLVs for add and modify commands are:

+TLVs for add and modify commands are::

    field            width    description

    ----------------------------------------------------

@@ -XXX,XX +XXX,XX @@ TLVs for add and modify commands are:

Additional TLVs based on flow table ID:

-Table ID 0: ingress port

+Table ID 0: ingress port::

    field            width    description

    ----------------------------------------------------

    OF_DPA_IN_PPORT        4    ingress physical port number

    OF_DPA_GOTO_TBL        2    goto table ID; zero to drop

-Table ID 10: vlan

+Table ID 10: vlan::

    field            width    description

    ----------------------------------------------------

@@ -XXX,XX +XXX,XX @@ Table ID 10: vlan

    OF_DPA_GOTO_TBL        2    goto table ID; zero to drop

    OF_DPA_NEW_VLAN_ID    2 (N)    new vlan ID

-Table ID 20: termination mac

+Table ID 20: termination mac::

    field            width    description

    ----------------------------------------------------

@@ -XXX,XX +XXX,XX @@ Table ID 20: termination mac

    OF_DPA_OUT_PPORT    2    if specified, must be

                    controller, set zero otherwise