Debian Codegraph @

runtime/transport/transport_msgs.h

raw
1 /* -*- linux-c -*-
2 * transport_msgs.h - messages exchanged between module and userspace
3 *
4 * Copyright (C) Red Hat Inc, 2006-2023
5 *
6 * This file is part of systemtap, and is free software. You can
7 * redistribute it and/or modify it under the terms of the GNU General
8 * Public License (GPL); either version 2, or (at your option) any
9 * later version.
10 */
11
12 /*
13 * NB: consider backward compatibility implications such as PR12612
14 * before changing existing message structures in any way.
15 */
16
17 #define STP_MODULE_NAME_LEN 128
18 #define STP_SYMBOL_NAME_LEN 128
19 #define STP_TZ_NAME_LEN 64
20 #define STP_REMOTE_URI_LEN 128
21
22 #define STAP_TRACE_MAGIC "\xF0\x9F\xA9\xBA" /* unicode stethoscope 🩺 in UTF-8 */
23 struct _stp_trace {
24 char magic[4]; /* framing helper */
25 uint32_t sequence; /* event number */
26 uint32_t pdu_len; /* length of data after this trace */
27 };
28
29 /* stp control channel command values */
30 enum
31 {
32 /** stapio sends a STP_START after recieving a STP_TRANSPORT from
33 the module. The module sends STP_START back with result of call
34 systemtap_module_init() which will install all initial probes. */
35 STP_START = 0x50, // renumbered in version 5.0 to force incompatibility
36 /** stapio sends STP_EXIT to signal it wants to stop the module
37 itself or in response to receiving a STP_REQUEST_EXIT.
38 The module sends STP_EXIT once _stp_clean_and_exit has been
39 called (the first time) in reponse to a STP_EXIT or an rmmod. */
40 STP_EXIT,
41 /** _stp_warn and _stp_error messages from the module. stapio
42 parses the start if the message payload string to determine
43 whether it is a WARNING: or ERROR:. */
44 STP_OOB_DATA,
45 /** Send by the module (tapset/system.stp) to request stapio to
46 execute a shell command with the given message payload. */
47 STP_SYSTEM,
48 /** modules sends STP_TRANSPORT to stapio when ready to recieve a
49 STP_START message. stapio sends STP_BULK and then STP_START
50 back. */
51 STP_TRANSPORT,
52 /** Never used. */
53 STP_CONNECT,
54 /** Never used. */
55 STP_DISCONNECT,
56 /** Send by the staprun when initializing relayfs in response to a
57 STP_TRANSPORT message with a (empty) 127 char payload. Silently
58 absorbed by module when in STP_BULKMODE (percpu files), otherwise
59 returns -EINVAL to indicate bulkmode is disabled. */
60 STP_BULK,
61 /** Send as first message from staprun stp_main_loop, but never
62 never acted upon. Used to be initial message for message to
63 start requestion symbol data (symbol data is now compiled
64 into the module). */
65 STP_READY,
66 /** Send by staprun at startup to notify module of where the kernel
67 (_stext) and all other modules are loaded.
68
69 PR26074: Also used to pass addresses of some unexported
70 kernel functions, most notably kallsyms_lookup_name (which
71 is used to retrieve yet other unexported functions). */
72 STP_RELOCATION,
73 /** Never used. deprecated STP_TRANSPORT_VERSION == 1 **/
74 STP_BUF_INFO,
75 /** Never used. */
76 STP_SUBBUFS_CONSUMED,
77 /** Used by the module only when STP_TRANSPORT_VERSION == 1 for
78 stapio to write realtime data packet to disk. */
79 STP_REALTIME_DATA,
80 /** Send by the module when it gets unloaded or STP_EXIT has been
81 received by stapio. */
82 STP_REQUEST_EXIT,
83 /** Send by staprun to notify module of current timezone.
84 Only send once at startup. */
85 STP_TZINFO,
86 /** Send by staprun to notify module of the user's privilege credentials.
87 Only send once at startup. */
88 STP_PRIVILEGE_CREDENTIALS,
89 /** Send by staprun to notify module of remote identity, if any.
90 Only send once at startup. */
91 STP_REMOTE_ID,
92 /** Placeholder, it was mistakenly labeled STP_MAX_CMD */
93 STP_MAX_CMD_PLACEHOLDER,
94 /** Sent by stapio after having recevied STP_TRANSPORT. Notifies
95 the module of the target namespaces pid.*/
96 STP_NAMESPACES_PID,
97 /** Sent by stapio after having recevied STP_TRANSPORT. Notifies
98 the module of the target mount namespace fd and the original
99 mount namespace fd. */
100 STP_MNT_NS_FDS,
101
102 /** INSERT NEW MESSAGE TYPES HERE */
103
104 /** Max number of message types, sanity check only. */
105 STP_MAX_CMD,
106 };
107
108 #ifdef DEBUG_TRANS
109 static const char *_stp_command_name[STP_MAX_CMD+1] = {
110 [STP_START]="STP_START",
111 "STP_EXIT",
112 "STP_OOB_DATA",
113 "STP_SYSTEM",
114 "STP_TRANSPORT",
115 "STP_CONNECT",
116 "STP_DISCONNECT",
117 "STP_BULK",
118 "STP_READY",
119 "STP_RELOCATION",
120 "STP_BUF_INFO",
121 "STP_SUBBUFS_CONSUMED",
122 "STP_REALTIME_DATA",
123 "STP_REQUEST_EXIT",
124 "STP_TZINFO",
125 "STP_PRIVILEGE_CREDENTIALS",
126 "STP_REMOTE_ID",
127 "STP_MAX_CMD_PLACEHOLDER",
128 "STP_NAMESPACE_PID",
129 "STP_MNT_NS_FDS",
130 [STP_MAX_CMD]="?" /* in control.c, STP_MAX_CMD represents unknown message numbers/names */
131 };
132 #endif /* DEBUG_TRANS */
133
134 /* control channel messages */
135
136 /* command to execute: module->stapio */
137 struct _stp_msg_cmd
138 {
139 char cmd[128];
140 };
141
142 /* Unwind data. stapio->module */
143 struct _stp_msg_unwind
144 {
145 /* the module name, or "*" for all */
146 char name[STP_MODULE_NAME_LEN];
147 /* length of unwind data */
148 uint32_t unwind_len;
149 /* data ...*/
150 };
151
152 /* Request to start probes. */
153 /* stapio->module->stapio */
154 struct _stp_msg_start
155 {
156 pid_t target;
157 int32_t res; // for reply: result of systemtap_module_init
158 };
159
160 /* target namespaces pid */
161 struct _stp_msg_ns_pid
162 {
163 pid_t target;
164 };
165
166 /* target & original mount namespaces' fds */
167 struct _stp_msg_mnt_ns_fds
168 {
169 int target_fd;
170 int orig_fd;
171 };
172
173 /* Unwind data. stapio->module */
174 struct _stp_msg_relocation
175 {
176 char module[STP_MODULE_NAME_LEN];
177 char reloc[STP_SYMBOL_NAME_LEN];
178 uint64_t address;
179 };
180
181 struct _stp_msg_tzinfo
182 {
183 int64_t tz_gmtoff;
184 char tz_name[STP_TZ_NAME_LEN];
185 };
186
187 struct _stp_msg_privilege_credentials
188 {
189 int32_t pc_group_mask;
190 };
191
192 struct _stp_msg_remote_id
193 {
194 int32_t remote_id;
195 char remote_uri[STP_REMOTE_URI_LEN];
196 };