Merge branch 'lukas/erts/tracing/tracer-move-extra-to-map/OTP-10267'

* lukas/erts/tracing/tracer-move-extra-to-map/OTP-10267:
  runtime_tools: Fix erl_tracer testcases
  runtime_tools: Fix documentation for dbg:p
  erts: Move tracer SecondTraceTerm to Opts map

1 files changed, 45 insertions, 51 deletions

diff --git a/erts/doc/src/erl_tracer.xml b/erts/doc/src/erl_tracer.xml
index d4c8bbad31..7841fdfd63 100644
--- a/erts/doc/src/erl_tracer.xml
+++ b/erts/doc/src/erl_tracer.xml
@@ -67,7 +67,7 @@
       <desc>
 	<p>The different trace tags that the tracer will be called with.
         Each trace tag is described in greater detail in
-        <seealso marker="#Module:trace/6">Module:trace/6</seealso>
+        <seealso marker="#Module:trace/5">Module:trace/5</seealso>
         </p>
       </desc>
     </datatype>
@@ -84,14 +84,18 @@
 	<p>The options for the tracee.</p>
         <taglist>
           <tag><c>timestamp</c></tag>
-          <item>If not set to <c>undefined</c>, the tracer has been requested to
-          include a timestamp.</item>
+          <item>If set the tracer has been requested to include a timestamp.</item>
+          <tag><c>extra</c></tag>
+          <item>If set the tracepoint has included additonal data about
+          the trace event. What the additional data is depends on which
+          <c>TraceTag</c> has been triggered. The <c>extra</c> trace data
+          corresponds to the fifth elemnt in the trace tuples described in
+          <seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>.</item>
           <tag><c>match_spec_result</c></tag>
-          <item>If not set to <c>true</c>, the tracer has been requested to
-          include the output of a match specification that was run.</item>
+          <item>If set the tracer has been requested to include the output
+          of a match specification that was run.</item>
           <tag><c>scheduler_id</c></tag>
-          <item>Set to a number if the scheduler id is to be included by the tracer.
-          Otherwise it is set to <c>undefined</c>.</item>
+          <item>Set the scheduler id is to be included by the tracer.</item>
         </taglist>
       </desc>
     </datatype>
@@ -115,23 +119,23 @@
    <taglist>
        <tag><seealso marker="#Module:enabled/3"><c>Module:enabled/3</c></seealso></tag>
        <item>Mandatory</item>
-       <tag><seealso marker="#Module:trace/6"><c>Module:trace/6</c></seealso></tag>
+       <tag><seealso marker="#Module:trace/5"><c>Module:trace/5</c></seealso></tag>
        <item>Mandatory</item>
        <tag><seealso marker="#Module:enabled_procs/3"><c>Module:enabled_procs/3</c></seealso></tag>
        <item>Optional</item>
-       <tag><seealso marker="#Module:trace_procs/6"><c>Module:trace_procs/6</c></seealso></tag>
+       <tag><seealso marker="#Module:trace_procs/5"><c>Module:trace_procs/5</c></seealso></tag>
        <item>Optional</item>
        <tag><seealso marker="#Module:enabled_ports/3"><c>Module:enabled_ports/3</c></seealso></tag>
        <item>Optional</item>
-       <tag><seealso marker="#Module:trace_ports/6"><c>Module:trace_ports/6</c></seealso></tag>
+       <tag><seealso marker="#Module:trace_ports/5"><c>Module:trace_ports/5</c></seealso></tag>
        <item>Optional</item>
        <tag><seealso marker="#Module:enabled_running_ports/3"><c>Module:enabled_running_ports/3</c></seealso></tag>
        <item>Optional</item>
-       <tag><seealso marker="#Module:trace_running_ports/6"><c>Module:trace_running_ports/6</c></seealso></tag>
+       <tag><seealso marker="#Module:trace_running_ports/5"><c>Module:trace_running_ports/5</c></seealso></tag>
        <item>Optional</item>
        <tag><seealso marker="#Module:enabled_running_procs/3"><c>Module:enabled_running_procs/3</c></seealso></tag>
        <item>Optional</item>
-       <tag><seealso marker="#Module:trace_running_procs/6"><c>Module:trace_running_procs/6</c></seealso></tag>
+       <tag><seealso marker="#Module:trace_running_procs/5"><c>Module:trace_running_procs/5</c></seealso></tag>
        <item>Optional</item>
    </taglist>
 
@@ -166,14 +170,13 @@
       </desc>
     </func>
     <func>
-      <name>Module:trace(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+      <name>Module:trace(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
       <fsummary>Check if a trace event should be generated.</fsummary>
       <type>
         <v>TraceTag = <seealso marker="#type-trace_tag">trace_tag()</seealso></v>
         <v>TracerState = term()</v>
         <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
         <v>FirstTraceTerm = term()</v>
-        <v>SecondTraceTerm = term() | undefined</v>
         <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
         <v>Result =  ok</v>
       </type>
@@ -182,17 +185,17 @@
         the <seealso marker="#Module:enabled/3">Module:enabled/3</seealso>
         callback returned <c>trace</c>. In it any side effects needed by
         the tracer should be done. The tracepoint payload is located in
-        the <c>FirstTraceTerm</c> and <c>SecondTraceTerm</c>. The content
-        of the TraceTerms depends on which <c>TraceTag</c> has been triggered.
-        The <c>FirstTraceTerm</c> and <c>SecondTraceTerm</c> correspond to the
-        fourth and fifth slot in the trace tuples described in
+        the <c>TraceTerm</c>. The content of the TraceTerm depends on which
+        <c>TraceTag</c> has been triggered.
+        The <c>TraceTerm</c> corresponds to the
+        fourth element in the trace tuples described in
         <seealso marker="erlang#trace_3_trace_messages">erlang:trace/3</seealso>.
-        If the tuple only has four elements, <c>SecondTraceTerm</c> will be
-        <c>undefined</c>.</p>
+        If the trace tuple has five elements, the fifth element will be sent as
+        the <c>extra</c> value in the <c>Opts</c> maps.</p>
       </desc>
     </func>
     <func>
-      <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, undefined, Opts) -> Result</name>
+      <name name="trace">Module:trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result</name>
       <fsummary>Check if a sequence trace event should be generated.</fsummary>
       <type>
         <v>TracerState = term()</v>
@@ -228,14 +231,13 @@
     </func>
 
     <func>
-        <name>Module:trace_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+        <name>Module:trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
         <fsummary>Check if a trace event should be generated.</fsummary>
         <type>
             <v>TraceTag = <seealso marker="#type-trace_tag_procs">trace_tag()</seealso></v>
             <v>TracerState = term()</v>
             <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
             <v>FirstTraceTerm = term()</v>
-            <v>SecondTraceTerm = term() | undefined</v>
             <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
             <v>Result = ok</v>
         </type>
@@ -243,7 +245,7 @@
             <p>This callback will be called when a tracepoint is triggered and
                 the <seealso marker="#Module:enabled_procs/3">Module:enabled_procs/3</seealso>
                 callback returned <c>trace</c>.</p>
-            <p>If <c>trace_procs/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+            <p>If <c>trace_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p>
         </desc>
     </func>
 
@@ -265,14 +267,13 @@
     </func>
 
     <func>
-        <name>Module:trace_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+        <name>Module:trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
         <fsummary>Check if a trace event should be generated.</fsummary>
         <type>
             <v>TraceTag = <seealso marker="#type-trace_tag_ports">trace_tag()</seealso></v>
             <v>TracerState = term()</v>
             <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
             <v>FirstTraceTerm = term()</v>
-            <v>SecondTraceTerm = term() | undefined</v>
             <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
             <v>Result = ok</v>
         </type>
@@ -280,7 +281,7 @@
             <p>This callback will be called when a tracepoint is triggered and
                 the <seealso marker="#Module:enabled_ports/3">Module:enabled_ports/3</seealso>
                 callback returned <c>trace</c>.</p>
-            <p>If <c>trace_ports/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+            <p>If <c>trace_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p>
         </desc>
     </func>
 
@@ -302,14 +303,13 @@
     </func>
 
     <func>
-        <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+        <name>Module:trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
         <fsummary>Check if a trace event should be generated.</fsummary>
         <type>
             <v>TraceTag = <seealso marker="#type-trace_tag_running_procs">trace_tag_running_procs()</seealso></v>
             <v>TracerState = term()</v>
             <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
             <v>FirstTraceTerm = term()</v>
-            <v>SecondTraceTerm = term() | undefined</v>
             <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
             <v>Result = ok</v>
         </type>
@@ -317,7 +317,7 @@
             <p>This callback will be called when a tracepoint is triggered and
                 the <seealso marker="#Module:enabled_running_procs/3">Module:enabled_running_procs/3</seealso>
                 callback returned <c>trace</c>.</p>
-            <p>If <c>trace_running_procs/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+            <p>If <c>trace_running_procs/5</c> is not defined <c>trace/5</c> will be called instead.</p>
         </desc>
     </func>
 
@@ -339,14 +339,13 @@
     </func>
 
     <func>
-        <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+        <name>Module:trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
         <fsummary>Check if a trace event should be generated.</fsummary>
         <type>
             <v>TraceTag = <seealso marker="#type-trace_tag_running_ports">trace_tag_running_ports()</seealso></v>
             <v>TracerState = term()</v>
             <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
             <v>FirstTraceTerm = term()</v>
-            <v>SecondTraceTerm = term() | undefined</v>
             <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
             <v>Result = ok</v>
         </type>
@@ -354,7 +353,7 @@
             <p>This callback will be called when a tracepoint is triggered and
                 the <seealso marker="#Module:enabled_running_ports/3">Module:enabled_running_ports/3</seealso>
                 callback returned <c>trace</c>.</p>
-            <p>If <c>trace_running_ports/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+            <p>If <c>trace_running_ports/5</c> is not defined <c>trace/5</c> will be called instead.</p>
         </desc>
     </func>
 
@@ -376,14 +375,13 @@
     </func>
 
     <func>
-        <name>Module:trace_call(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+        <name>Module:trace_call(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
         <fsummary>Check if a trace event should be generated.</fsummary>
         <type>
             <v>TraceTag = <seealso marker="#type-trace_tag_call">trace_tag_call()</seealso></v>
             <v>TracerState = term()</v>
             <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
             <v>FirstTraceTerm = term()</v>
-            <v>SecondTraceTerm = term() | undefined</v>
             <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
             <v>Result = ok</v>
         </type>
@@ -391,7 +389,7 @@
             <p>This callback will be called when a tracepoint is triggered and
                 the <seealso marker="#Module:enabled_call/3">Module:enabled_call/3</seealso>
                 callback returned <c>trace</c>.</p>
-            <p>If <c>trace_call/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+            <p>If <c>trace_call/5</c> is not defined <c>trace/5</c> will be called instead.</p>
         </desc>
     </func>
 
@@ -413,14 +411,13 @@
     </func>
 
     <func>
-        <name>Module:trace_send(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+        <name>Module:trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
         <fsummary>Check if a trace event should be generated.</fsummary>
         <type>
             <v>TraceTag = <seealso marker="#type-trace_tag_send">trace_tag_send()</seealso></v>
             <v>TracerState = term()</v>
             <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
             <v>FirstTraceTerm = term()</v>
-            <v>SecondTraceTerm = term() | undefined</v>
             <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
             <v>Result =  ok</v>
         </type>
@@ -428,7 +425,7 @@
             <p>This callback will be called when a tracepoint is triggered and
                 the <seealso marker="#Module:enabled_send/3">Module:enabled_send/3</seealso>
                 callback returned <c>trace</c>.</p>
-            <p>If <c>trace_send/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+            <p>If <c>trace_send/5</c> is not defined <c>trace/5</c> will be called instead.</p>
         </desc>
     </func>
 
@@ -450,14 +447,13 @@
     </func>
 
     <func>
-        <name>Module:trace_receive(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+        <name>Module:trace_receive(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
         <fsummary>Check if a trace event should be generated.</fsummary>
         <type>
             <v>TraceTag = <seealso marker="#type-trace_tag_receive">trace_tag_receive()</seealso></v>
             <v>TracerState = term()</v>
             <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
             <v>FirstTraceTerm = term()</v>
-            <v>SecondTraceTerm = term() | undefined</v>
             <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
             <v>Result =  ok</v>
         </type>
@@ -465,7 +461,7 @@
             <p>This callback will be called when a tracepoint is triggered and
                 the <seealso marker="#Module:enabled_receive/3">Module:enabled_receive/3</seealso>
                 callback returned <c>trace</c>.</p>
-            <p>If <c>trace_receive/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+            <p>If <c>trace_receive/5</c> is not defined <c>trace/5</c> will be called instead.</p>
         </desc>
     </func>
 
@@ -487,14 +483,13 @@
     </func>
 
     <func>
-        <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, FirstTraceTerm, SecondTraceTerm, Opts) -> Result</name>
+        <name>Module:trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result</name>
         <fsummary>Check if a trace event should be generated.</fsummary>
         <type>
             <v>TraceTag = <seealso marker="#type-trace_tag_gc">trace_tag_gc()</seealso></v>
             <v>TracerState = term()</v>
             <v>Tracee = <seealso marker="#type-tracee">tracee()</seealso></v>
             <v>FirstTraceTerm = term()</v>
-            <v>SecondTraceTerm = term() | undefined</v>
             <v>Opts = <seealso marker="#type-trace_opts">trace_opts()</seealso></v>
             <v>Result =  ok</v>
         </type>
@@ -502,7 +497,7 @@
             <p>This callback will be called when a tracepoint is triggered and
                 the <seealso marker="#Module:enabled_garbage_collection/3">Module:enabled_garbage_collection/3</seealso>
                 callback returned <c>trace</c>.</p>
-            <p>If <c>trace_garbage_collection/6</c> is not defined <c>trace/6</c> will be called instead.</p>
+            <p>If <c>trace_garbage_collection/5</c> is not defined <c>trace/5</c> will be called instead.</p>
         </desc>
     </func>
 
@@ -543,7 +538,7 @@ ok
     <pre>
 -module(erl_msg_tracer).
 
--export([enabled/3, trace/6, load/0]).
+-export([enabled/3, trace/5, load/0]).
 
 load() ->
     erlang:load_nif("erl_msg_tracer", []).
@@ -551,7 +546,7 @@ load() ->
 enabled(_, _, _) ->
     error.
 
-trace(_, _, _,_, _, _) ->
+trace(_, _, _,_, _) ->
     error.
     </pre>
     <p>erl_msg_tracer.c</p>
@@ -569,7 +564,7 @@ static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
 
 static ErlNifFunc nif_funcs[] = {
     {"enabled", 3, enabled},
-    {"trace", 6, trace}
+    {"trace", 5, trace}
 };
 
 ERL_NIF_INIT(erl_msg_tracer, nif_funcs, load, NULL, upgrade, unload)
@@ -632,9 +627,8 @@ static ERL_NIF_TERM enabled(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
  * argv[0]: TraceTag, should only be 'send'
  * argv[1]: TracerState, process to send {argv[2], argv[4]} to
  * argv[2]: Tracee
- * argv[3]: Message, ignored
- * argv[4]: Recipient
- * argv[5]: Options, ignored
+ * argv[3]: Recipient
+ * argv[4]: Options, ignored
  */
 static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
 {