qemu-e2k/docs/qemu-option-trace.rst.inc

27 lines
889 B
PHP
Raw Normal View History

qemu-nbd: Convert invocation documentation to rST The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo format, which we present to the user as: * a qemu-nbd manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-nbd manpage * part of the interop/ Sphinx manual This follows the same pattern as commit 27a296fce982 did for the qemu-ga manpage. All the content of the old manpage is retained, except that I have dropped the "This is free software; see the source for copying conditions. There is NO warranty..." text that was in the old AUTHOR section; Sphinx's manpage builder doesn't expect that much text in the AUTHOR section, and since none of our other manpages have it it seems easiest to delete it rather than try to figure out where else in the manpage to put it. The only other textual change is that I have had to give the --nocache option its own description ("Equivalent to --cache=none") because Sphinx doesn't have an equivalent of using item/itemx to share a description between two options. Some minor aspects of the formatting have changed, to suit what is easiest for Sphinx to output. (The most notable is that Sphinx option section option syntax doesn't support '--option foo=bar' with bar underlined rather than bold, so we have to switch to '--option foo=BAR' instead.) The contents of qemu-option-trace.texi are now duplicated in docs/interop/qemu-option-trace.rst.inc, until such time as we complete the conversion of the other files which use it; since it has had only 3 changes in 3 years, this shouldn't be too awkward a burden. (We use .rst.inc because if this file fragment has a .rst extension then Sphinx complains about not seeing it in a toctree.) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-2-peter.maydell@linaro.org
2020-01-23 16:22:39 +01:00
Specify tracing options.
``[enable=]PATTERN``
qemu-nbd: Convert invocation documentation to rST The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo format, which we present to the user as: * a qemu-nbd manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-nbd manpage * part of the interop/ Sphinx manual This follows the same pattern as commit 27a296fce982 did for the qemu-ga manpage. All the content of the old manpage is retained, except that I have dropped the "This is free software; see the source for copying conditions. There is NO warranty..." text that was in the old AUTHOR section; Sphinx's manpage builder doesn't expect that much text in the AUTHOR section, and since none of our other manpages have it it seems easiest to delete it rather than try to figure out where else in the manpage to put it. The only other textual change is that I have had to give the --nocache option its own description ("Equivalent to --cache=none") because Sphinx doesn't have an equivalent of using item/itemx to share a description between two options. Some minor aspects of the formatting have changed, to suit what is easiest for Sphinx to output. (The most notable is that Sphinx option section option syntax doesn't support '--option foo=bar' with bar underlined rather than bold, so we have to switch to '--option foo=BAR' instead.) The contents of qemu-option-trace.texi are now duplicated in docs/interop/qemu-option-trace.rst.inc, until such time as we complete the conversion of the other files which use it; since it has had only 3 changes in 3 years, this shouldn't be too awkward a burden. (We use .rst.inc because if this file fragment has a .rst extension then Sphinx complains about not seeing it in a toctree.) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-2-peter.maydell@linaro.org
2020-01-23 16:22:39 +01:00
Immediately enable events matching *PATTERN*
(either event name or a globbing pattern). This option is only
available if QEMU has been compiled with the ``simple``, ``log``
or ``ftrace`` tracing backend. To specify multiple events or patterns,
specify the :option:`-trace` option multiple times.
Use :option:`-trace help` to print a list of names of trace points.
``events=FILE``
qemu-nbd: Convert invocation documentation to rST The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo format, which we present to the user as: * a qemu-nbd manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-nbd manpage * part of the interop/ Sphinx manual This follows the same pattern as commit 27a296fce982 did for the qemu-ga manpage. All the content of the old manpage is retained, except that I have dropped the "This is free software; see the source for copying conditions. There is NO warranty..." text that was in the old AUTHOR section; Sphinx's manpage builder doesn't expect that much text in the AUTHOR section, and since none of our other manpages have it it seems easiest to delete it rather than try to figure out where else in the manpage to put it. The only other textual change is that I have had to give the --nocache option its own description ("Equivalent to --cache=none") because Sphinx doesn't have an equivalent of using item/itemx to share a description between two options. Some minor aspects of the formatting have changed, to suit what is easiest for Sphinx to output. (The most notable is that Sphinx option section option syntax doesn't support '--option foo=bar' with bar underlined rather than bold, so we have to switch to '--option foo=BAR' instead.) The contents of qemu-option-trace.texi are now duplicated in docs/interop/qemu-option-trace.rst.inc, until such time as we complete the conversion of the other files which use it; since it has had only 3 changes in 3 years, this shouldn't be too awkward a burden. (We use .rst.inc because if this file fragment has a .rst extension then Sphinx complains about not seeing it in a toctree.) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-2-peter.maydell@linaro.org
2020-01-23 16:22:39 +01:00
Immediately enable events listed in *FILE*.
The file must contain one event name (as listed in the ``trace-events-all``
file) per line; globbing patterns are accepted too. This option is only
available if QEMU has been compiled with the ``simple``, ``log`` or
``ftrace`` tracing backend.
``file=FILE``
qemu-nbd: Convert invocation documentation to rST The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo format, which we present to the user as: * a qemu-nbd manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-nbd manpage * part of the interop/ Sphinx manual This follows the same pattern as commit 27a296fce982 did for the qemu-ga manpage. All the content of the old manpage is retained, except that I have dropped the "This is free software; see the source for copying conditions. There is NO warranty..." text that was in the old AUTHOR section; Sphinx's manpage builder doesn't expect that much text in the AUTHOR section, and since none of our other manpages have it it seems easiest to delete it rather than try to figure out where else in the manpage to put it. The only other textual change is that I have had to give the --nocache option its own description ("Equivalent to --cache=none") because Sphinx doesn't have an equivalent of using item/itemx to share a description between two options. Some minor aspects of the formatting have changed, to suit what is easiest for Sphinx to output. (The most notable is that Sphinx option section option syntax doesn't support '--option foo=bar' with bar underlined rather than bold, so we have to switch to '--option foo=BAR' instead.) The contents of qemu-option-trace.texi are now duplicated in docs/interop/qemu-option-trace.rst.inc, until such time as we complete the conversion of the other files which use it; since it has had only 3 changes in 3 years, this shouldn't be too awkward a burden. (We use .rst.inc because if this file fragment has a .rst extension then Sphinx complains about not seeing it in a toctree.) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-2-peter.maydell@linaro.org
2020-01-23 16:22:39 +01:00
Log output traces to *FILE*.
This option is only available if QEMU has been compiled with
the ``simple`` tracing backend.