perf script: Add more documentation about the -f/--fields parameters
Arnaldo Carvalho de Melo [Wed, 30 Mar 2011 18:30:43 +0000 (15:30 -0300)]
Using the commit log for 2c9e45f.

Cc: David Ahern <>
Cc: Frederic Weisbecker <>
Cc: Ingo Molnar <>
Cc: Mike Galbraith <>
Cc: Paul Mackerras <>
Cc: Peter Zijlstra <>
Cc: Stephane Eranian <>
Cc: Tom Zanussi <>
LKML-Reference: <new-submission>
Signed-off-by: Arnaldo Carvalho de Melo <>


index 66f040b..86c87e2 100644 (file)
@@ -113,13 +113,61 @@ OPTIONS
         Do various checks like samples ordering and lost events.
         Comma separated list of fields to print. Options are:
         comm, tid, pid, time, cpu, event, trace, sym. Field
-        list must be prepended with the type, trace, sw or hw,
+        list can be prepended with the type, trace, sw or hw,
         to indicate to which event type the field list applies.
         e.g., -f sw:comm,tid,time,sym  and -f trace:time,cpu,trace
+               perf script -f <fields>
+       is equivalent to:
+               perf script -f trace:<fields> -f sw:<fields> -f hw:<fields>
+       i.e., the specified fields apply to all event types if the type string
+       is not given.
+       The arguments are processed in the order received. A later usage can
+       reset a prior request. e.g.:
+               -f trace: -f comm,tid,time,sym
+       The first -f suppresses trace events (field list is ""), but then the
+       second invocation sets the fields to comm,tid,time,sym. In this case a
+       warning is given to the user:
+               "Overriding previous field request for all events."
+       Alternativey, consider the order:
+               -f comm,tid,time,sym -f trace:
+       The first -f sets the fields for all events and the second -f
+       suppresses trace events. The user is given a warning message about
+       the override, and the result of the above is that only S/W and H/W
+       events are displayed with the given fields.
+       For the 'wildcard' option if a user selected field is invalid for an
+       event type, a message is displayed to the user that the option is
+       ignored for that type. For example:
+               $ perf script -f comm,tid,trace
+               'trace' not valid for hardware events. Ignoring.
+               'trace' not valid for software events. Ignoring.
+       Alternatively, if the type is given an invalid field is specified it
+       is an error. For example:
+        perf script -v -f sw:comm,tid,trace
+        'trace' not valid for software events.
+       At this point usage is displayed, and perf-script exits.
+       Finally, a user may not set fields to none for all event types.
+       i.e., -f "" is not allowed.
         vmlinux pathname