1// Copyright 2023 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5/*
6Package raw provides an interface to interpret and emit Go execution traces.
7It can interpret and emit execution traces in its wire format as well as a
8bespoke but simple text format.
9
10The readers and writers in this package perform no validation on or ordering of
11the input, and so are generally unsuitable for analysis. However, they're very
12useful for testing and debugging the tracer in the runtime and more sophisticated
13trace parsers.
14
15# Text format specification
16
17The trace text format produced and consumed by this package is a line-oriented
18format.
19
20The first line in each text trace is the header line.
21
22	Trace Go1.XX
23
24Following that is a series of event lines. Each event begins with an
25event name, followed by zero or more named unsigned integer arguments.
26Names are separated from their integer values by an '=' sign. Names can
27consist of any UTF-8 character except '='.
28
29For example:
30
31	EventName arg1=23 arg2=55 arg3=53
32
33Any amount of whitespace is allowed to separate each token. Whitespace
34is identified via unicode.IsSpace.
35
36Some events have additional data on following lines. There are two such
37special cases.
38
39The first special case consists of events with trailing byte-oriented data.
40The trailer begins on the following line from the event. That line consists
41of a single argument 'data' and a Go-quoted string representing the byte data
42within. Note: an explicit argument for the length is elided, because it's
43just the length of the unquoted string.
44
45For example:
46
47	String id=5
48		data="hello world\x00"
49
50These events are identified in their spec by the HasData flag.
51
52The second special case consists of stack events. These events are identified
53by the IsStack flag. These events also have a trailing unsigned integer argument
54describing the number of stack frame descriptors that follow. Each stack frame
55descriptor is on its own line following the event, consisting of four signed
56integer arguments: the PC, an integer describing the function name, an integer
57describing the file name, and the line number in that file that function was at
58at the time the stack trace was taken.
59
60For example:
61
62	Stack id=5 n=2
63		pc=1241251 func=3 file=6 line=124
64		pc=7534345 func=6 file=3 line=64
65*/
66package raw
67