[trace][intelpt] Support system-wide tracing [2] - Add a dummy --per-core-tracing option

This updates the documentation of the gdb-remote protocol, as well as the help messages, to include the new --per-core-tracing option.

Differential Revision: https://reviews.llvm.org/D124640

1 files changed, 40 insertions, 11 deletions

diff --git a/lldb/docs/lldb-gdb-remote.txt b/lldb/docs/lldb-gdb-remote.txt
index 545fbb46ae24..50a47ccf50bf 100644
--- a/lldb/docs/lldb-gdb-remote.txt
+++ b/lldb/docs/lldb-gdb-remote.txt
@@ -283,7 +283,7 @@ read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAA
 //        Tracing technology name, e.g. intel-pt, arm-coresight.
 //
 //    /* thread tracing only */
-//    "tids": [<decimal integer>],
+//    "tids"?: [<decimal integer>],
 //        Individual threads to trace.
 //
 //    ... other parameters specific to the provided tracing type
@@ -298,16 +298,25 @@ read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAA
 // INTEL-PT
 //  intel-pt supports both "thread tracing" and "process tracing".
 //
-//  "Process tracing" is implemented by tracing each thread individually, but
-//  managed by the same "process trace" instance.
-//  Each actual thread trace, either from "process tracing" or "thread tracing",
+//  "Process tracing" is implemented in two different ways. If the
+//  "perCoreTracing" option is false, then each thread is traced individually
+//  but managed by the same "process trace" instance. This means that the
+//  amount of trace buffers used is proportional to the number of running
+//  threads. This is the recommended option unless the number of threads is
+//  huge. If "perCoreTracing" is true, then each cpu core is traced invidually
+//  instead of each thread, which uses a fixed number of trace buffers, but
+//  might result in less data available for less frequent threads. See
+//  "perCoreTracing" below for more information.
+//
+//  Each actual trace buffer, either from "process tracing" or "thread tracing",
 //  is stored in an in-memory circular buffer, which keeps the most recent data.
 //
 //  Additional params in the input schema:
 //   {
-//     "threadBufferSize": <decimal integer>,
-//         Trace buffer size per thread in bytes. It must be a power of 2
-//         greater than or equal to 4096 (2^12) bytes.
+//     "traceBufferSize": <decimal integer>,
+//         Size in bytes used by each individual per-thread or per-core trace
+//         buffer. It must be a power of 2 greater than or equal to 4096 (2^12)
+//         bytes.
 //
 //     "enableTsc": <boolean>,
 //         Whether to enable TSC timestamps or not. This is supported on
@@ -342,15 +351,35 @@ read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAA
 //          0 if supported.
 //
 //     /* process tracing only */
+//     "perCoreTracing": <boolean>
+//         Instead of having an individual trace buffer per thread, this option
+//         triggers the collection on a per cpu core basis. This effectively
+//         traces the entire activity on all cores. At decoding time, in order
+//         to correctly associate a decoded instruction with a thread, the
+//         context switch trace of each core is needed, as well as a record per
+//         cpu indicating which thread was running on each core when tracing
+//         started. These secondary traces are correlated with the intel-pt
+//         trace by comparing TSC timestamps.
+//
+//         This option forces the capture of TSC timestamps (see "enableTsc").
+//
+//         Note: This option can't be used simulatenously with any other trace
+//         sessions because of its system-wide nature.
+//
+//     /* process tracing only */
 //     "processBufferSizeLimit": <decimal integer>,
 //         Maximum total buffer size per process in bytes.
 //         This limit applies to the sum of the sizes of all trace buffers for
 //         the current process, excluding the ones started with "thread tracing".
 //
-//         Whenever a thread is attempted to be traced due to "process tracing"
-//         and the limit would be reached, the process is stopped with a
-//         "tracing" reason along with a meaningful description, so that the
-//         user can retrace the process if needed.
+//         If "perCoreTracing" is false, whenever a thread is attempted to be
+//         traced due to "process tracing" and the limit would be reached, the
+//         process is stopped with a "tracing" reason along with a meaningful
+//         description, so that the user can retrace the process if needed.
+//
+//         If "perCoreTracing" is true, then starting the system-wide trace
+//         session fails if all the individual per-core trace buffers require
+//         in total more memory that the limit impossed by this parameter.
 //   }
 //
 //  Notes: