[Qemu-devel] [PATCH 02/10] trace-tcg: Add documentation

[Lluís Vilanova]

Signed-off-by: Lluís Vilanova <address@hidden>
---
 docs/tracing.txt |   40 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 40 insertions(+), 0 deletions(-)

diff --git a/docs/tracing.txt b/docs/tracing.txt
index 853cbf8..44c5dba 100644
--- a/docs/tracing.txt
+++ b/docs/tracing.txt
@@ -244,3 +244,43 @@ In this case you should declare such event with the 
"disable" property. This
 will effectively disable the event at compile time (by using the "nop" 
backend),
 thus having no performance impact at all on regular builds (i.e., unless you
 edit the "trace-events" file).
+
+=== "tcg" ===
+
+Code from the guest generated by TCG can be traced by defining an event with 
the
+"tcg" event property.
+
+In addition to the regular "trace_<eventname>" routine in the "trace.h" header,
+events with the "tcg" property will also provide the TCG helper routine
+"gen_helper_trace_<eventname>". This routine can be called during TCG code
+generation as any other TCG helper to automatically generate TCG code to call
+"trace_<eventname>" during TCG code execution.
+
+The notable difference is that these events can be declared in the
+"trace-events" file with both basic types as well as TCG types. The
+"gen_helper_trace_<eventname>" routine will transparently take care of turning
+any non-TCG argument into a TCG value.
+
+For example, the event:
+
+    tcg foo(uint8_t a1, TCGv_i32 a2) "a1=%d a2=%d"
+
+Can be invoked from TCG code as:
+
+    uint8_t a1 = ...;
+    TCGv_i32 a2 = ...;
+    gen_helper_trace_foo(a1, a2);
+
+And the intermediate boilerplate code will take care of generating the TCG code
+to call:
+
+    void trace_foo(uint8_t a1, uint32_t a2);
+
+=== "tcg-vcpu" ===
+
+Events with the "tcg" property will generate code helpers with the
+"TCG_CALL_CONST" flag (see "tcg/README" and "tcg/tcg.h"), which produces faster
+code that is unable to reliably access the state of the vCPU.
+
+Using the "tcg-vcpu" property will generate a slower TCG helper that will be
+able to reliably get and set values from the vCPU.