/
BINARY_PROTOCOL
245 lines (177 loc) · 8.31 KB
/
BINARY_PROTOCOL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
Binary data protocol
--------------------
The binary data is generated by the main tracing module and parsed by
the post-processor. The protocol consists from the handshake packet
sent right after estabilishing the connection and data packets
generated by trace events.
Handshake packet:
The handshake packet is the first packet of the binary data protocol.
It contains information about protocol version and source system
architecture.
The handshake packet is endian independant - any system/architecture
should be able to read/parse it and decide if it supports the
specified protocol version/system architecture or not.
The size of handshake packet is padded to ensure 4 byte alignment of
the following packages.
[id][size][version][archictecture]
[id] - the binary protocol identification, 0xF0 (1 byte).
[size] - the packet size (1 byte)
[version] - the packet version [major][minor]
[major] - the version major number (1 byte)
[minor] - the version minor number (1 byte)
[architecture] - the source system architecture [length][text]
[length] - the text length - n (1 bytes)
[text] - the text data (n bytes);
[endianess] - endianess of the source system (1 byte)
0 - little endian, 1 big endian
[pointer size] - size of pointers in the source system (1 byte)
usually 4 for 32 bit systems and 8 for 64 bit systems.
The rest of packets are endian dependent and have the following
generic format:
[type][size][data]
[type] - the packet type (4 bytes)
[size] - the data length n (4 bytes)
[data] - the packet data (n bytes)
The data members inside packets are aligned by 4 byte boundaries to
prevent from unaligned memory access which can be problem on some
architectures.
Generic data types used in the protocol:
[byte] - byte/char, used only in handshake packet (1 byte)
[dword] - dword/int (4 bytes)
[pointer] - pointer/void * (4 or 8 bytes, depending on system architecture)
[string] - length prefixed string [length][text]
[length] - the string length - n (word)
[text] - the string data (n bytes). The text is padded with
'\0' characters so that the whole string size is 4 byte aligned.
A special case is NULL string, where [length] is zero (implying
no [text] data), but the string is still padded with two '\0'
characters so that the whole string size is 4 byte aligned.
The Protocol defines following packet types:
1. Process information [PINF]
The process information packet is sent when the tracing is started.
[pid][timestamp][name]
[pid] - process identifier (dword).
[timestamp] - trace starting timestamp [secs][usecs].
[secs] - seconds since the Epoch (dword).
[usecs] - microsecond since the Epoch (dword).
[depth] - the backtrace depth setting [v1.2] (dword)
[name] - the process name (string).
2. Module information [MINF]
The module information packet is sent when tracing is started.
[id][version][name]
[id] - the module identifier. Used to estabilish tracing record
ownership when multiple tracing modules are used
[version] - module version (dword). High word contains major version
number and low word - minor.
[name] - the module name (string).
3. Memory mapping [MMAP]
The memory mapping packets contains start/end addresses and names of
the executable modules mapped in memory.
[from][to][path]
[from] - start adress (pointer)
[to] - end address (pointer)
[path] - the module path (string)
4. Context registry [CTXR]
The context registry packet is sent when a call context is created by
sp_context_create function. It contains context id and name.
[id][name]
[id] - context id (dword)
[name] - context name (string)
5. Function call [CALL]
Function call packet is sent when a function call has been done.
[timestamp][resource type][context][type][name][id][size]
[timestamp] - the timestamp containing milliseconds since
midnight(?) (dword).
[resource type] - the resource type id.
0 if only one resource type is tracked.
[context] - the call context (dword)
[type] - the call type (allocation/deallocation/copying) (dword)
[name] - the function name (string)
[id] - the resource identifier (pointer)
[size] - the resource size (integer)
6. Backtrace [BTRC]
The backtrace packet is sent after function call packet.
It contains stack trace of the last function call.
[nframes][address][address]...[address]
[nframes] - number of addresses (dword)
[address] - return address from the corresponding stack frame (pointer)
7. Function arguments [ARGS]
The function arguments packet is an optional packet which could be
sent after FC+BT packets. It contains detalized information about
function arguments.
[number][arg1][arg2]...[argN]
[number] - the number of function arguments (dword)
[arg1][arg2]...[argN] - function argument list
[argX] - the function argument X ([name][value])
[name] - the function argument name (string)
[value] - te function argument value (string)
8. New library [NLIB]
The new library packet is sent at beginning and whenever a new library
is loaded with dlopen() function. This packet is only sent from the
main tracing module to the pre-processor and is not stored into log
file or forwarded to post-processor.
[name] - the library name (string). Specify * to scan all libraries.
9. Heap information [HINF]
The heap information packet is sent at the end of the report (before
the trace is disabled or target process has been finished). It
contains heap statistics returned by mallinfo() function if
sp_rtrace_store_heap_info() was called during the trace.
[hbottom][htop][arena][ordblks][smblks][hblks][hblkhd][usmblks][fsmblks]
[uordblks][fordblks][keepcost]
[hbottom] - heap bottom (pointer);
[htop] - heap top (pointer);
[arena] - the total size of non-mmapped bytes allocated
from system (dword).
[ordblks] - the number of free chunks (dword).
[smblks] - the number of fastbin blocks
(small non-reused freed chunks) (dword).
[hblks] - the number of mmapped regions (dword).
[hblkhd] - the total size of mmapped regions, in bytes
(dword).
[usmblks] - the maximum total allocated space (after trimming
this is larger than current total) (dword).
[fsmblks] - the space available in freed fastbin blocks (dword).
[uordblks] - the total size of allocated memory, both normal and
mmapped (dword).
[fordblks] - the total size of free space (dword).
[keepcost] - the ideal total size of bytes that could be released
to system via malloc_trim() if paging restrictions
are ignored (dword).
10. Output settings [OCFG]
The output settings packet contains post-processor options and output
directory path. This packet is used to pass the post-processor options
back to the sp-rtrace when it's used in toggle mode to enable tracing.
The OS packet is not stored on disk or passed to post-processor.
[path][options]
[path] - the output directory (string)
[options] - the post-processor options (string)
11. Resource registry [RESR]
The resource registry packet contains resource type id and name. If
multiple resource types are being tracked, then resource id is used
to identify the tracked resource type in function call records.
[id][name]
[id] - the resource type id (dword)
[flags] - flags describing resource behaviour (dword)
0x0001 - refcount flag. Set if the resource allocs/frees
use reference counting.
[type] - the resource type (string)
[desc] - the resource desription (string)
12. File attachment [FILE]
File attachment packet is used to bundle the sp-rtrace log with
a custom data stored in a file. The attached files are optional
and are used only by specific post-processing tools. The files
are stored in the same directory as the sp-rtrace log files.
[name][path]
[name] - the attachment name (string). The name must consist
of alphanumeric charaters.
[path] - the attached file name (string)
The name is used to identify attachment type, while the path points
to the real file name.
--------------
Version log
v1.4
Added file attachment packet.
v1.2
Added backtrace depth field to process info packet.
v1.0
Initial protocol release.