[Qemu-devel] [PATCH v2 6/6] trace: Update doc for trace events group

[Mark Wu <wudxw@linux.vnet.ibm.com>]

Signed-off-by: Mark Wu <wudxw@linux.vnet.ibm.com>
---
 docs/tracing.txt |   29 ++++++++++++++++++++++++++---
 1 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/docs/tracing.txt b/docs/tracing.txt
index 95ca16c..139a331 100644
--- a/docs/tracing.txt
+++ b/docs/tracing.txt
@@ -16,6 +16,7 @@ for debugging, profiling, and observing execution.
 
    echo bdrv_aio_readv   > /tmp/events
    echo bdrv_aio_writev >> /tmp/events
+   echo group:virtio >> /tmp/events
 
 3. Run the virtual machine to produce a trace file:
 
@@ -53,6 +54,16 @@ source code like this:
         return ptr;
     }
 
+== Trace events group ==
+
+Trace events group is used to represent a set of trace events added for the same
+component or feature. Each trace events group starts with a line containing the
+string "group_start:group-name" and end with a line containing the string
+"group_end". The range of a trace events group is determined by the "tracetool"
+script when it processes the "trace-events" file. You can change the state of a
+group of trace events at one time through trace events group.
+
+
 === Declaring trace events ===
 
 The "tracetool" script produces the trace.h header file which is included by
@@ -106,8 +117,8 @@ respectively.  This ensures portability between 32- and 64-bit platforms.
 
 == Generic interface and monitor commands ==
 
-You can programmatically query and control the dynamic state of trace events
-through a backend-agnostic interface:
+You can programmatically query and control the dynamic state of trace events or
+groups through a backend-agnostic interface:
 
 * trace_print_events
 
@@ -122,6 +133,11 @@ through a backend-agnostic interface:
     [...]
     trace_event_set_state("virtio_irq", false); /* disable */
 
+* trace_print_groups
+
+* trace_event_group_set_state
+  Enables or disables a given group of trace events at runtime inside QEMU.
+
 Note that some of the backends do not provide an implementation for this
 interface, in which case QEMU will just print a warning.
 
@@ -131,12 +147,19 @@ This functionality is also provided through monitor commands:
   View available trace events and their state.  State 1 means enabled, state 0
   means disabled.
 
+* info trace-groups
+  View available trace event groups and their state.  State 1 means enabled, state 0
+  means disabled.
+
 * trace-event NAME on|off
   Enable/disable a given trace event.
 
+* trace-group NAME on|off
+  Enable/disable a given trace event group.
+
 The "-trace events=<file>" command line argument can be used to enable the
 events listed in <file> from the very beginning of the program. This file must
-contain one event name per line.
+contain one event name or one group name, which is prefixed by "group:".
 
 == Trace backends ==
 
-- 
1.7.1