aboutsummaryrefslogtreecommitdiff
path: root/docs/tracing.txt
diff options
context:
space:
mode:
authorLluís <xscript@gmx.net>2011-08-31 20:31:24 +0200
committerStefan Hajnoczi <stefanha@linux.vnet.ibm.com>2011-09-01 10:34:54 +0100
commit31965ae27bc11e90674be12584bb201b83df5aef (patch)
tree95e1c094a394d1ee56f1e1dc242a2c23df6bfb54 /docs/tracing.txt
parentfc764105397fa55e7c03f42a6d019063ec0cad00 (diff)
downloadqemu-31965ae27bc11e90674be12584bb201b83df5aef.zip
qemu-31965ae27bc11e90674be12584bb201b83df5aef.tar.gz
qemu-31965ae27bc11e90674be12584bb201b83df5aef.tar.bz2
trace: always compile support for controlling and querying trace event states
The current interface is generic for this small set of operations, and thus other backends can easily modify the "trace/control.c" file to add their own implementation. Signed-off-by: Lluís Vilanova <vilanova@ac.upc.edu>
Diffstat (limited to 'docs/tracing.txt')
-rw-r--r--docs/tracing.txt48
1 files changed, 30 insertions, 18 deletions
diff --git a/docs/tracing.txt b/docs/tracing.txt
index 1ad106a..41eb8e6 100644
--- a/docs/tracing.txt
+++ b/docs/tracing.txt
@@ -108,6 +108,36 @@ portability macros, ensure they are preceded and followed by double quotes:
of trace events. Marking trace events disabled by default saves the user
from having to manually disable noisy trace events.
+== Generic interface and monitor commands ==
+
+You can programmatically query and control the dynamic state of trace events
+through a backend-agnostic interface:
+
+* trace_print_events
+
+* trace_event_set_state
+ Enables or disables trace events at runtime inside QEMU.
+ The function returns "true" if the state of the event has been successfully
+ changed, or "false" otherwise:
+
+ #include "trace/control.h"
+
+ trace_event_set_state("virtio_irq", true); /* enable */
+ [...]
+ trace_event_set_state("virtio_irq", false); /* disable */
+
+Note that some of the backends do not provide an implementation for this
+interface, in which case QEMU will just print a warning.
+
+This functionality is also provided through monitor commands:
+
+* info trace-events
+ View available trace events and their state. State 1 means enabled, state 0
+ means disabled.
+
+* trace-event NAME on|off
+ Enable/disable a given trace event.
+
== Trace backends ==
The "tracetool" script automates tedious trace event code generation and also
@@ -157,27 +187,9 @@ unless you have specific needs for more advanced backends.
flushed and emptied. This means the 'info trace' will display few or no
entries if the buffer has just been flushed.
-* info trace-events
- View available trace events and their state. State 1 means enabled, state 0
- means disabled.
-
-* trace-event NAME on|off
- Enable/disable a given trace event.
-
* trace-file on|off|flush|set <path>
Enable/disable/flush the trace file or set the trace file name.
-==== Enabling/disabling trace events programmatically ====
-
-The st_change_trace_event_state() function can be used to enable or disable trace
-events at runtime inside QEMU:
-
- #include "trace.h"
-
- st_change_trace_event_state("virtio_irq", true); /* enable */
- [...]
- st_change_trace_event_state("virtio_irq", false); /* disable */
-
==== Analyzing trace files ====
The "simple" backend produces binary trace files that can be formatted with the