[IPC Protocol] Extend EventPipe command to configure a user_events eventpipe session

Author: mdh1418

documentation/design-docs/ipc-protocol.md

@@ -351,6 +351,7 @@ enum class EventPipeCommandId : uint8_t
     CollectTracing2 = 0x03, // create/start a given session with/without rundown
     CollectTracing3 = 0x04, // create/start a given session with/without collecting stacks
     CollectTracing4 = 0x05, // create/start a given session with specific rundown keyword
+    CollectTracing5 = 0x06, // create/start a given session with/without user_events
 }
 ```
 See: [EventPipe Commands](#EventPipe-Commands)
@@ -406,6 +407,7 @@ enum class EventPipeCommandId : uint8_t
     CollectTracing2 = 0x03, // create/start a given session with/without rundown
     CollectTracing3 = 0x04, // create/start a given session with/without collecting stacks
     CollectTracing4 = 0x05, // create/start a given session with specific rundown keyword
+    CollectTracing5 = 0x06, // create/start a given session with/without user_events
 }
 ```
 EventPipe Payloads are encoded with the following rules:
@@ -608,7 +610,7 @@ Followed by an Optional Continuation of a `nettrace` format stream of events.
 
 Command Code: `0x0205`
 
-The `CollectTracing4` command is an extension of the `CollectTracing3` command - its behavior is the same as `CollectTracing3` command, except the requestRundown field is replaced by the rundownKeyword field to allow customizing the set of rundown events to be fired. 
+The `CollectTracing4` command is an extension of the `CollectTracing3` command - its behavior is the same as `CollectTracing3` command, except the requestRundown field is replaced by the rundownKeyword field to allow customizing the set of rundown events to be fired.
 
 A rundown keyword of `0x80020139` has the equivalent behavior as `CollectTracing3` with `requestRundown=true` and rundown keyword of `0` has the equivalent behavior as `requestRundown=false`.
 
@@ -622,6 +624,7 @@ Header: `{ Magic; Size; 0x0205; 0x0000 }`
 * `uint circularBufferMB`: The size of the circular buffer used for buffering event data while streaming
 * `uint format`: 0 for the legacy NetPerf format and 1 for the NetTrace format
 * `ulong rundownKeyword`: Indicates the keyword for the rundown provider
+* `bool requestStackwalk`: Indicates whether stacktrace information should be recorded.
 * `array<provider_config> providers`: The providers to turn on for the streaming session
 
 A `provider_config` is composed of the following data:
@@ -669,6 +672,107 @@ Payload
 ```
 Followed by an Optional Continuation of a `nettrace` format stream of events.
 
+### `CollectTracing5`
+
+Command Code: `0x0206`
+
+The `CollectTracing5` command is an extension of the `CollectTracing4` command. Its behavior is similar to `CollectTracing4`, but it introduces a new field to enable particular runtime events to be written under prescribed `user_events` tracepoints. This allows the runtime to register tracepoints based on the provider configurations passed in and write directly to the `user_events_data` file.
+
+> Note available for .NET 10.0 and later.
+
+#### Inputs:
+
+Header: `{ Magic; Size; 0x0206; 0x0000 }`
+
+* `uint circularBufferMB`: The size of the circular buffer used for buffering event data while streaming
+* `uint format`: 0 for the legacy NetPerf format and 1 for the NetTrace format
+* `ulong rundownKeyword`: Indicates the keyword for the rundown provider
+* `bool requestStackwalk`: Indicates whether stacktrace information should be recorded.
+* `bool userEventsRequested`: Indicates whether `user_events` should be enabled
+* `array<provider_config> providers`: The providers to turn on for the streaming session
+
+A `provider_config` is composed of the following data:
+* `ulong keywords`: The keywords to turn on with this provider
+* `uint logLevel`: The level of information to turn on
+* `string provider_name`: The name of the provider
+* `string filter_data` (optional): Filter information for callbacks
+* `event_filter filter`: Defines rules for filtering this provider's Event IDs, using either an allow list or a deny list.
+* `tracepoint_config config` (required when `userEventsRequested` is true): Maps filtered Event IDs to tracepoints. If an Event ID is excluded by `event_filter`, it will not be written to any tracepoint.
+
+A `event_filter` is comprised of the following data:
+* `bool allow`: 0 for deny list, 1 for allow list
+* `array<uint> event_ids`: List of Event IDs to deny or allow.
+
+A `tracepoint_config` is comprised of the following data:
+* `string default_tracepoint_name`: The default tracepoint filtered Event IDs will be written to unless otherwise specified by `tracepoints`.
+* `array<tracepoint_set> tracepoints` (optional): Specifies alternate tracepoint subsets of Event IDs will be written to instead of the default tracepoint.
+
+A `tracepoint_set` is comprised of the following data:
+* `string tracepoint_name`: The tracepoint that the following subset of Event IDs should be written to.
+* `array<uint> tracepoint_event_ids`: The Event IDs to be written to `tracepoint_name`.
+
+> See ETW documentation for a more detailed explanation of Keywords, Filters, and Log Level.
+
+#### Returns (as an IPC Message Payload):
+
+Header: `{ Magic; 28; 0xFF00; 0x0000; }`
+
+`CollectTracing5` returns:
+* `ulong sessionId`: the ID for the stream session starting on the current connection
+
+##### Details:
+
+Input:
+```
+Payload
+{
+    uint circularBufferMB,
+    uint format,
+    ulong rundownKeyword,
+    bool requestStackwalk,
+    bool userEventsRequested,
+    array<provider_config> providers
+}
+
+provider_config
+{
+    ulong keywords,
+    uint logLevel,
+    string provider_name,
+    string filter_data (optional),
+    event_filter filter,
+    tracepoint_config config
+}
+
+event_filter
+{
+    bool allow,
+    array<uint> event_ids
+}
+
+tracepoint_config
+{
+    string default_tracepoint_name,
+    array<tracepoint_set> tracepoints
+}
+
+tracepoint_set
+{
+    string tracepoint_name,
+    array<uint> event_ids
+}
+```
+
+Returns:
+```c
+Payload
+{
+    ulong sessionId
+}
+```
+
+Followed by an Optional Continuation of a `nettrace` format stream of events or direct writes to the file descriptor if `userEventsRequested` is enabled.
+
 ### `StopTracing`
 
 Command Code: `0x0201`