Skip to content

Commit 87902f0

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

File tree

1 file changed

+33
-0
lines changed

1 file changed

+33
-0
lines changed

documentation/design-docs/ipc-protocol.md

+33
Original file line numberDiff line numberDiff line change
@@ -1013,6 +1013,39 @@ 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+
```
1021+
struct iovec io[5];
1022+
1023+
io[0].iov_base = &myTracepointIndex; // __u32 from event_reg
1024+
io[0].iov_len = sizeof(myTracepointIndex);
1025+
io[1].iov_base = &event_id // EventID defined by EventSource/native manifest
1026+
io[1].iov_len = sizeof(event_id)
1027+
io[2].iov_base = &this_event_payload; // __rel_loc char[]
1028+
io[2].iov_len = sizeof(this_event_payload);
1029+
io[3].iov_base = &this_event_meta; // __rel_loc char[]
1030+
io[3].iov_len = sizeof(this_event_meta);
1031+
io[4].iov_base = &actual_data; // char[]
1032+
io[4].iov_len = actual_data_len;
1033+
1034+
writev(ep_session->data_fd, (const struct iovec *)io, 5);
1035+
```
1036+
1037+
The `__rel_loc` is the relative dynamic array attribute described [here](https://lwn.net/Articles/876682/).
1038+
1039+
The payload points at a blob of data with the same format as an EventPipe payload – the concatenated encoded values for all the parameters
1040+
1041+
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).
1042+
1043+
> 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.
1044+
1045+
### Which events have metadata?
1046+
1047+
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.
1048+
10161049
## Dump Commands
10171050

10181051
### `CreateCoreDump`

0 commit comments

Comments
 (0)