diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/about/deprecated.rst | 34 | ||||
| -rw-r--r-- | docs/about/removed-features.rst | 9 | ||||
| -rw-r--r-- | docs/devel/codebase.rst | 6 | ||||
| -rw-r--r-- | docs/devel/qapi-code-gen.rst | 53 | ||||
| -rw-r--r-- | docs/devel/qapi-domain.rst | 4 | ||||
| -rw-r--r-- | docs/interop/qemu-ga-ref.rst | 3 | ||||
| -rw-r--r-- | docs/interop/qemu-qmp-ref.rst | 2 | ||||
| -rw-r--r-- | docs/interop/qemu-storage-daemon-qmp-ref.rst | 2 | ||||
| -rw-r--r-- | docs/sphinx/qmp_lexer.py | 2 | ||||
| -rw-r--r-- | docs/system/arm/imx8mp-evk.rst | 12 | ||||
| -rw-r--r-- | docs/system/arm/virt.rst | 4 |
11 files changed, 84 insertions, 47 deletions
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index e2b4f07..0538144 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -292,6 +292,36 @@ Big-Endian variants of MicroBlaze ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` ma Both ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` were added for little endian CPUs. Big endian support is not tested. +Mips ``mipssim`` machine (since 10.0) +''''''''''''''''''''''''''''''''''''' + +Linux dropped support for this virtual machine type in kernel v3.7, and +there does not seem to be anybody around who is still using this board +in QEMU: Most former MIPS-related people are working on other architectures +in their everyday job nowadays, and we are also not aware of anybody still +using old binaries with this board (i.e. there is also no binary available +online to check that this board did not completely bitrot yet). It is +recommended to use another MIPS machine for future MIPS code development +instead. + +RISC-V default machine option (since 10.0) +'''''''''''''''''''''''''''''''''''''''''' + +RISC-V defines ``spike`` as the default machine if no machine option is +given in the command line. This happens because ``spike`` is the first +RISC-V machine implemented in QEMU and setting it as default was +convenient at that time. Now we have 7 riscv64 and 6 riscv32 machines +and having ``spike`` as a default is no longer justified. This default +will also promote situations where users think they're running ``virt`` +(the most used RISC-V machine type in 10.0) when in fact they're +running ``spike``. + +Removing the default machine option forces users to always set the machine +they want to use and avoids confusion. Existing users of the ``spike`` +machine must ensure that they're setting the ``spike`` machine in the +command line (``-M spike``). + + Backend options --------------- @@ -422,7 +452,7 @@ Backend ``memory`` (since 9.0) ``reconnect`` (since 9.2) ^^^^^^^^^^^^^^^^^^^^^^^^^ -The ``reconnect`` option only allows specifiying second granularity timeouts, +The ``reconnect`` option only allows specifying second granularity timeouts, which is not enough for all types of use cases, use ``reconnect-ms`` instead. @@ -432,7 +462,7 @@ Net device options Stream ``reconnect`` (since 9.2) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The ``reconnect`` option only allows specifiying second granularity timeouts, +The ``reconnect`` option only allows specifying second granularity timeouts, which is not enough for all types of use cases, use ``reconnect-ms`` instead. VFIO device options diff --git a/docs/about/removed-features.rst b/docs/about/removed-features.rst index 2527a91..790a5e4 100644 --- a/docs/about/removed-features.rst +++ b/docs/about/removed-features.rst @@ -858,6 +858,15 @@ QEMU. Since all recent x86 hardware from the past >10 years is capable of the 64-bit x86 extensions, a corresponding 64-bit OS should be used instead. +32-bit hosts for 64-bit guests (removed in 10.0) +'''''''''''''''''''''''''''''''''''''''''''''''' + +In general, 32-bit hosts cannot support the memory space or atomicity +requirements of 64-bit guests. Prior to 10.0, QEMU attempted to +work around the atomicity issues in system mode by running all vCPUs +in a single thread context; in user mode atomicity was simply broken. +From 10.0, QEMU has disabled configuration of 64-bit guests on 32-bit hosts. + Guest Emulator ISAs ------------------- diff --git a/docs/devel/codebase.rst b/docs/devel/codebase.rst index 1b09953..ef98578 100644 --- a/docs/devel/codebase.rst +++ b/docs/devel/codebase.rst @@ -5,7 +5,7 @@ Codebase This section presents the various parts of QEMU and how the codebase is organized. -Beyond giving succint descriptions, the goal is to offer links to various +Beyond giving succinct descriptions, the goal is to offer links to various parts of the documentation/codebase. Subsystems @@ -67,7 +67,7 @@ yet, so sometimes the source code is all you have. * `chardev <https://gitlab.com/qemu-project/qemu/-/tree/master/chardev>`_: Various backends used by char devices. * `common-user <https://gitlab.com/qemu-project/qemu/-/tree/master/common-user>`_: - User-mode assembly code for dealing with signals occuring during syscalls. + User-mode assembly code for dealing with signals occurring during syscalls. * `configs <https://gitlab.com/qemu-project/qemu/-/tree/master/configs>`_: Makefiles defining configurations to build QEMU. * `contrib <https://gitlab.com/qemu-project/qemu/-/tree/master/contrib>`_: @@ -102,7 +102,7 @@ yet, so sometimes the source code is all you have. * `.gitlab-ci.d <https://gitlab.com/qemu-project/qemu/-/tree/master/.gitlab-ci.d>`_: `CI <ci>` yaml and scripts. * `include <https://gitlab.com/qemu-project/qemu/-/tree/master/include>`_: - All headers associated to different subsystems in QEMU. The hierachy used + All headers associated to different subsystems in QEMU. The hierarchy used mirrors source code organization and naming. * `hw <https://gitlab.com/qemu-project/qemu/-/tree/master/hw>`_: `Devices <device-emulation>` and boards emulation. Devices are categorized by diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index f9cfe87..231cc0f 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -763,8 +763,8 @@ Names beginning with ``x-`` used to signify "experimental". This convention has been replaced by special feature "unstable". Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let -you violate naming rules. Use for new code is strongly discouraged. See -`Pragma directives`_ for details. +you violate naming rules. Use for new code is strongly discouraged. +See `Pragma directives`_ for details. Downstream extensions @@ -1013,7 +1013,7 @@ like this:: document the success and the error response, respectively. "Errors" sections should be formatted as an rST list, each entry -detailing a relevant error condition. For example:: +detailing a relevant error condition. For example:: # Errors: # - If @device does not exist, DeviceNotFound @@ -1026,31 +1026,28 @@ definition. QMP). In other sections, the text is formatted, and rST markup can be used. -QMP Examples can be added by using the ``.. qmp-example::`` -directive. In its simplest form, this can be used to contain a single -QMP code block which accepts standard JSON syntax with additional server -directionality indicators (``->`` and ``<-``), and elisions (``...``). +QMP Examples can be added by using the ``.. qmp-example::`` directive. +In its simplest form, this can be used to contain a single QMP code +block which accepts standard JSON syntax with additional server +directionality indicators (``->`` and ``<-``), and elisions. An +elision is commonly ``...``, but it can also be or a pair of ``...`` +with text in between. Optionally, a plaintext title may be provided by using the ``:title:`` -directive option. If the title is omitted, the example title will +directive option. If the title is omitted, the example title will default to "Example:". A simple QMP example:: # .. qmp-example:: - # :title: Using query-block # - # -> { "execute": "query-block" } - # <- { ... } + # -> { "execute": "query-name" } + # <- { "return": { "name": "Fred" } } -More complex or multi-step examples where exposition is needed before or -between QMP code blocks can be created by using the ``:annotated:`` -directive option. When using this option, nested QMP code blocks must be -entered explicitly with rST's ``::`` syntax. - -Highlighting in non-QMP languages can be accomplished by using the -``.. code-block:: lang`` directive, and non-highlighted text can be -achieved by omitting the language argument. +More complex or multi-step examples where exposition is needed before +or between QMP code blocks can be created by using the ``:annotated:`` +directive option. When using this option, nested QMP code blocks must +be entered explicitly with rST's ``::`` syntax. For example:: @@ -1061,11 +1058,21 @@ For example:: # This is a more complex example that can use # ``arbitrary rST syntax`` in its exposition:: # - # -> { "execute": "query-block" } - # <- { ... } + # -> { "execute": "query-block" } + # <- { "return": [ + # { + # "device": "ide0-hd0", + # ... + # } + # ... more ... + # ] } # # Above, lengthy output has been omitted for brevity. +Highlighting in non-QMP languages can be accomplished by using the +``.. code-block:: lang`` directive, and non-highlighted text can be +achieved by omitting the language argument. + Examples of complete definition documentation:: @@ -1466,7 +1473,9 @@ As an example, we'll use the following schema, which describes a single complex user-defined type, along with command which takes a list of that type as a parameter, and returns a single element of that type. The user is responsible for writing the implementation of -qmp_my_command(); everything else is produced by the generator. :: +qmp_my_command(); everything else is produced by the generator. + +:: $ cat example-schema.json { 'struct': 'UserDefOne', diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index a748529..1123872 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -41,7 +41,7 @@ Schema or generating documentation from code that exists. It is merely the rST syntax used to describe things. For instance, the Sphinx Python domain adds syntax like ``:py:func:`` for describing Python functions in documentation, but it's the autodoc module that is responsible for -reading python code and generating such syntax. QAPI is analagous here: +reading Python code and generating such syntax. QAPI is analogous here: qapidoc.py is responsible for reading the QAPI Schema and generating rST syntax, and qapi_domain.py is responsible for translating that special syntax and providing APIs for Sphinx internals. @@ -514,7 +514,7 @@ the definition's "fully qualified name", allowing two different namespaces to create an otherwise identically named definition. This directive also influences how reference resolution works for any -references that do not explicity specify a namespace, so this directive +references that do not explicitly specify a namespace, so this directive can be used to nudge references into preferring targets from within that namespace. diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst index 19b5c7a..25f6e24 100644 --- a/docs/interop/qemu-ga-ref.rst +++ b/docs/interop/qemu-ga-ref.rst @@ -1,9 +1,6 @@ QEMU Guest Agent Protocol Reference =================================== -.. contents:: - :depth: 3 - .. qapi-doc:: qga/qapi-schema.json :transmogrify: :namespace: QGA diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst index ef8792b..3bc1ca1 100644 --- a/docs/interop/qemu-qmp-ref.rst +++ b/docs/interop/qemu-qmp-ref.rst @@ -4,7 +4,7 @@ QEMU QMP Reference Manual ========================= .. contents:: - :depth: 3 + :local: .. qapi-doc:: qapi/qapi-schema.json :transmogrify: diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst index d0228d6..dc7bde2 100644 --- a/docs/interop/qemu-storage-daemon-qmp-ref.rst +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst @@ -2,7 +2,7 @@ QEMU Storage Daemon QMP Reference Manual ======================================== .. contents:: - :depth: 3 + :local: .. qapi-doc:: storage-daemon/qapi/qapi-schema.json :transmogrify: diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py index a59de8a..7b3b808 100644 --- a/docs/sphinx/qmp_lexer.py +++ b/docs/sphinx/qmp_lexer.py @@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer): 'root': [ (r'-> ', token.Generic.Prompt), (r'<- ', token.Generic.Prompt), - (r' ?\.{3} ?', token.Generic.Prompt), + (r'\.{3}( .* \.{3})?', token.Comment.Multiline), ] } diff --git a/docs/system/arm/imx8mp-evk.rst b/docs/system/arm/imx8mp-evk.rst index 00527b0..b2f7d29 100644 --- a/docs/system/arm/imx8mp-evk.rst +++ b/docs/system/arm/imx8mp-evk.rst @@ -35,7 +35,7 @@ Direct Linux Kernel Boot Probably the easiest way to get started with a whole Linux system on the machine is to generate an image with Buildroot. Version 2024.11.1 is tested at the time -of writing and involves three steps. First run the following commands in the +of writing and involves two steps. First run the following commands in the toplevel directory of the Buildroot source tree: .. code-block:: bash @@ -50,14 +50,6 @@ it and resize the SD card image to a power of two: $ qemu-img resize sdcard.img 256M -Finally, the device tree needs to be patched with the following commands which -will remove the ``cpu-idle-states`` properties from CPU nodes: - -.. code-block:: bash - - $ dtc imx8mp-evk.dtb | sed '/cpu-idle-states/d' > imx8mp-evk-patched.dts - $ dtc imx8mp-evk-patched.dts -o imx8mp-evk-patched.dtb - Now that everything is prepared the machine can be started as follows: .. code-block:: bash @@ -65,6 +57,6 @@ Now that everything is prepared the machine can be started as follows: $ qemu-system-aarch64 -M imx8mp-evk -smp 4 -m 3G \ -display none -serial null -serial stdio \ -kernel Image \ - -dtb imx8mp-evk-patched.dtb \ + -dtb imx8mp-evk.dtb \ -append "root=/dev/mmcblk2p2" \ -drive file=sdcard.img,if=sd,bus=2,format=raw,id=mmcblk2 diff --git a/docs/system/arm/virt.rst b/docs/system/arm/virt.rst index adf446c..6a719b9 100644 --- a/docs/system/arm/virt.rst +++ b/docs/system/arm/virt.rst @@ -70,11 +70,11 @@ Supported guest CPU types: - ``cortex-a76`` (64-bit) - ``cortex-a710`` (64-bit) - ``a64fx`` (64-bit) -- ``host`` (with KVM only) +- ``host`` (with KVM and HVF only) - ``neoverse-n1`` (64-bit) - ``neoverse-v1`` (64-bit) - ``neoverse-n2`` (64-bit) -- ``max`` (same as ``host`` for KVM; best possible emulation with TCG) +- ``max`` (same as ``host`` for KVM and HVF; best possible emulation with TCG) Note that the default is ``cortex-a15``, so for an AArch64 guest you must specify a CPU type. |