Skip to content

Commit 1ba9499

Browse files
committed
[Docs][IPC Protocol] Detail user_events format
1 parent efe387a commit 1ba9499

File tree

1 file changed

+28
-0
lines changed

1 file changed

+28
-0
lines changed

documentation/design-docs/ipc-protocol.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1013,6 +1013,34 @@ struct cmsghdr {
10131013

10141014
For parsing the file descriptor passed with SCM_RIGHTS, the runtime will `recvmsg` the message and only care about the control message containing ancillary data. It will read one byte from the `msg_iov` buffer just to receive the ancillary data, but it will disregard the contents of the `msg_iov` buffers.
10151015

1016+
### User_events format
1017+
1018+
When writing events to their mapped user_events tracepoints prescribed by the `tracepoint_config` in the [User_events session payload](#user_events-session-payload), the runtime will adapt the [user_events writing protocol](https://docs.kernel.org/trace/user_events.html#writing-data) to write the event as:
1019+
```
1020+
struct iovec io[3];
1021+
__rel_loc char[] event_payload;
1022+
__rel_loc char[] event_metadata;
1023+
1024+
io[0].iov_base = &tracepoint_write_index;
1025+
io[0].iov_len = sizeof(tracepoint_write_index);
1026+
io[1].iov_base = &event_payload;
1027+
io[1].iov_len = sizeof(event_payload);
1028+
io[2].iov_base = &event_metadata;
1029+
io[2].iov_len = sizeof(event_metadata);
1030+
```
1031+
1032+
The `__rel_loc` is the relative dynamic array attribute described [here](https://lwn.net/Articles/876682/).
1033+
1034+
The payload points at a blob of data with the same format as an EventPipe payload – the concatenated encoded values for all the parameters
1035+
1036+
The metadata either points at nothing if the event doesn’t have metadata, or it points at a metadata blob matching the NetTrace version 5 formatting convention. Specifically it is the data that would be stored inside the PayloadBytes area of an event blob within a MetadataBlock described [here](https://github.com/microsoft/perfview/blob/main/src/TraceEvent/EventPipe/NetTraceFormat_v5.md#metadata-event-encoding).
1037+
1038+
> NOTE: V5 and V6 metadata formats have the same info, but they aren’t formatted identically. Parsing and reserialization is required to convert between the two.
1039+
1040+
### Which events have metadata?
1041+
1042+
The runtime will keep track per-session whether it has sent a particular event before. The first time each event is sent during a session, metadata will be included, and otherwise, it will be left empty. As a special case, runtime events currently implemented in native code will never send metadata.
1043+
10161044
## Dump Commands
10171045

10181046
### `CreateCoreDump`

0 commit comments

Comments
 (0)