libtracefs: Clarify the tracefs_synth_create() man page

Commit Message

Steven Rostedt May 30, 2023, 6:02 a.m. UTC

From: "Steven Rostedt (Google)" <[e-mail]>

The man page for tracefs_synth_create() and tracefs_synth_set_instance()
suggests that if a synthetic event is created in a specific instance, then
it can only be used by that instance. This is incorrect. Synthetic events
created anywhere are global, and can be used by all instances. Update the
man pages to explicitly express this.

Signed-off-by: Steven Rostedt (Google) <[e-mail]>
---
 Documentation/libtracefs-synth2.txt | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

Patch

diff --git a/Documentation/libtracefs-synth2.txt b/Documentation/libtracefs-synth2.txt
index d94fa7ce88a2..77cdd0199a58 100644
--- a/Documentation/libtracefs-synth2.txt
+++ b/Documentation/libtracefs-synth2.txt
@@ -46,11 +46,14 @@  as a field for both events to calculate the delta in nanoseconds, or use
 *TRACEFS_TIMESTAMP_USECS* as the compare fields for both events to calculate the
 delta in microseconds. This is used as the example below.
 
-*tracefs_synth_create*() creates the synthetic event in the system. By default, the synthetic
-events are created in the top trace instance and apply across all instances.
-The *tracefs_synth_set_instance()* API can be used to set a custom instance, where the synthetic
-event will be created. In that case the event operates only in that instance. A synthetic event
-must be created with *tracefs_synth_alloc*(3) before it can be created.
+*tracefs_synth_create*() creates the synthetic event in the system. By default,
+the histogram triggers are created in the top trace instance, as any synthetic
+event can be used globally across all instances. In case an application wants
+to keep the histogram triggers out of the top level instance, it can use
+*tracefs_synth_set_instance()* to have the histograms used for creating the
+synthetic event in an instance other than the top level.  A synthetic event
+descriptor must be created with *tracefs_synth_alloc*(3) before this can be
+used to create it on the system.
 
 *tracefs_synth_destroy*() destroys the synthetic event. It will attempt to stop the running of it in
 its instance (top by default), but if its running in another instance this may fail as busy.
@@ -77,9 +80,14 @@  then save the given _save_fields_ list. The fields will be stored in the histogr
 "hist" file of the event that can be retrieved with *tracefs_event_file_read*(3).
 _var_ must be one of the _name_ elements used in *tracefs_synth_add_end_field*(3).
 
-*tracefs_synth_set_instance()* Set the trace instance, where the synthetic event will be
-created. By default, the top instance is used. This API must be called before the call to
-*tracefs_synth_create()*, in order to use the new instance when creating the event.
+*tracefs_synth_set_instance()* Set the trace instance, where the histogram
+triggers that create the synthetic event will be created. By default, the top
+instance is used. This API must be called before the call to
+*tracefs_synth_create()*, in order to use the new instance when creating the
+event.  Note, that even if the synthetic event is created in an instance, it is
+still visible by all other instances including the top level. That is, other
+instances can enable the created synthetic event and have it traced in the
+buffers that belong to the instance that enabled it.
 
 RETURN VALUE
 ------------