dyninst/decode: decoding of template segments (#43007)

### What does this PR do?

This PR implements the decoding of template segments. It tries to respect the size limits of the relevant RFC and to produce an output format that will look broadly familiar to a Go developer while still being reasonable.

### Describe how you validated your changes

There's some testing.

### Additional Notes

Part of [DEBUG-4034](https://datadoghq.atlassian.net/browse/DEBUG-4034)


[DEBUG-4034]: https://datadoghq.atlassian.net/browse/DEBUG-4034?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Co-authored-by: grantseltzer <[email protected]>
Co-authored-by: andrew.werner <[email protected]>

Author: ajwerner

pkg/dyninst/compiler/testdata/snapshot/simple.arch=amd64,toolchain=go1.23.11.sm.txt

@@ -79,7 +79,7 @@ type Decoder struct {
 
 	// These fields are initialized and reset for each message.
 	snapshotMessage snapshotMessage
-	entry           captureEvent
+	entryOrLine     captureEvent
 	_return         captureEvent
 	line            lineCaptureData
 }
@@ -128,7 +128,7 @@ func NewDecoder(
 			decoder.typesByGoRuntimeType[goRuntimeType] = id
 		}
 	}
-	decoder.entry.encodingContext = encodingContext{
+	decoder.entryOrLine.encodingContext = encodingContext{
 		typesByID:            decoder.decoderTypes,
 		typesByGoRuntimeType: decoder.typesByGoRuntimeType,
 		typeResolver:         typeNameResolver,
@@ -203,8 +203,8 @@ func (d *Decoder) Decode(
 }
 
 func (d *Decoder) resetForNextMessage() {
-	clear(d.entry.dataItems)
-	d.entry.clear()
+	clear(d.entryOrLine.dataItems)
+	d.entryOrLine.clear()
 	d.line.clear()
 	d._return.clear()
 	d.snapshotMessage = snapshotMessage{}
@@ -226,6 +226,7 @@ type snapshotMessage struct {
 	Debugger  debuggerData     `json:"debugger"`
 	Timestamp int              `json:"timestamp"`
 	Duration  uint64           `json:"duration,omitzero"`
+	Message   messageData      `json:"message,omitempty"`
 }
 
 func (s *snapshotMessage) init(
@@ -244,23 +245,23 @@ func (s *snapshotMessage) init(
 	if event.EntryOrLine == nil {
 		return nil, fmt.Errorf("entry event is nil")
 	}
-	if err := decoder.entry.init(
+	if err := decoder.entryOrLine.init(
 		event.EntryOrLine, decoder.program.Types, &s.Debugger.EvaluationErrors,
 	); err != nil {
 		return nil, err
 	}
-	probeEvent := decoder.probeEvents[decoder.entry.rootType.ID]
+	probeEvent := decoder.probeEvents[decoder.entryOrLine.rootType.ID]
 	probe := probeEvent.probe
 	header, err := event.EntryOrLine.Header()
 	if err != nil {
 		return probe, fmt.Errorf("error getting header %w", err)
 	}
 	switch probeEvent.event.Kind {
 	case ir.EventKindEntry:
-		s.Debugger.Snapshot.Captures.Entry = &decoder.entry
+		s.Debugger.Snapshot.Captures.Entry = &decoder.entryOrLine
 	case ir.EventKindLine:
 		decoder.line.sourceLine = probeEvent.event.SourceLine
-		decoder.line.capture = &decoder.entry
+		decoder.line.capture = &decoder.entryOrLine
 		s.Debugger.Snapshot.Captures.Lines = &decoder.line
 	}
 	var returnHeader *output.EventHeader
@@ -389,5 +390,14 @@ func (s *snapshotMessage) init(
 	s.Logger.ThreadID = int(header.Goid)
 	s.Debugger.Snapshot.Probe.ID = probe.GetID()
 	s.Debugger.Snapshot.Stack.frames = stackFrames
+
+	if probe.Template != nil {
+		s.Message = messageData{
+			entryOrLine: &decoder.entryOrLine,
+			_return:     &decoder._return,
+			template:    probe.Template,
+		}
+	}
+
 	return probe, nil
 }

pkg/dyninst/compiler/testdata/snapshot/simple.arch=amd64,toolchain=go1.24.3.sm.txt

@@ -44,8 +44,9 @@ func FuzzDecoder(f *testing.F) {
 			EntryOrLine: output.Event(item),
 			ServiceName: "foo",
 		}, &noopSymbolicator{}, []byte{})
-		require.Empty(t, decoder.entry.dataItems)
-		require.Empty(t, decoder.entry.currentlyEncoding)
+		require.Empty(t, decoder.entryOrLine.dataItems)
+		require.Empty(t, decoder.entryOrLine.currentlyEncoding)
+		require.Empty(t, decoder._return.dataItems)
 	})
 }
 
@@ -58,7 +59,10 @@ type (
 			Message    string `json:"message"`
 		} `json:"evaluationErrors,omitempty"`
 	}
-	eventCaptures struct{ Debugger debugger }
+	eventCaptures struct {
+		Debugger debugger
+		Message  string `json:"message,omitempty"`
+	}
 )
 
 // TestDecoderManually is a test that manually constructs an event and decodes
@@ -81,11 +85,14 @@ func TestDecoderManually(t *testing.T) {
 			var e eventCaptures
 			require.NoError(t, json.Unmarshal(buf, &e))
 			require.Equal(t, c.expected, e.Debugger.Snapshot.Captures.Entry.Arguments)
-			require.Empty(t, decoder.entry.dataItems)
-			require.Empty(t, decoder.entry.currentlyEncoding)
-			require.Nil(t, decoder.entry.rootType)
-			require.Nil(t, decoder.entry.rootData)
-			require.Zero(t, decoder.entry.evaluationErrors)
+			if c.expectedMessage != "" {
+				require.Equal(t, c.expectedMessage, e.Message)
+			}
+			require.Empty(t, decoder.entryOrLine.dataItems)
+			require.Empty(t, decoder.entryOrLine.currentlyEncoding)
+			require.Nil(t, decoder.entryOrLine.rootType)
+			require.Nil(t, decoder.entryOrLine.rootData)
+			require.Zero(t, decoder.entryOrLine.evaluationErrors)
 			require.Zero(t, decoder.snapshotMessage)
 		})
 	}
@@ -115,28 +122,33 @@ type testCase struct {
 	probeName        string
 	eventConstructor func(testing.TB, *ir.Program) []byte
 	expected         any
+	expectedMessage  string
 }
 
 var cases = []testCase{
 	{
 		probeName:        "stringArg",
 		eventConstructor: simpleStringArgEvent,
 		expected:         simpleStringArgExpected,
+		expectedMessage:  "s: abcdefghijklmnop",
 	},
 	{
 		probeName:        "mapArg",
 		eventConstructor: simpleMapArgEvent,
 		expected:         simpleMapArgExpected,
+		expectedMessage:  "m: map[a: 1]",
 	},
 	{
 		probeName:        "bigMapArg",
 		eventConstructor: simpleBigMapArgEvent,
 		expected:         simpleBigMapArgExpected,
+		expectedMessage:  "m: map[b: {Field1: 1, Field2: 0, Field3: 0, Field4: 0, Field5: 0, ...}}]",
 	},
 	{
 		probeName:        "PointerChainArg",
 		eventConstructor: simplePointerChainArgEvent,
 		expected:         simplePointerChainArgExpected,
+		expectedMessage:  "ptr: 17",
 	},
 }
 
@@ -181,14 +193,14 @@ func simpleStringArgEvent(t testing.TB, irProg *ir.Program) []byte {
 	}
 	require.NotNil(t, stringType)
 	require.NotNil(t, eventType)
-	require.Equal(t, uint32(17), eventType.GetByteSize())
+	require.Equal(t, uint32(33), eventType.GetByteSize())
 
 	var item []byte
 	eventHeader := output.EventHeader{
 		Data_byte_len: uint32(
 			unsafe.Sizeof(output.EventHeader{}) +
 				1 /* bitset */ + unsafe.Sizeof(output.DataItemHeader{}) +
-				16 + 7 /* padding */ +
+				32 + 7 /* padding */ +
 				unsafe.Sizeof(output.DataItemHeader{}) +
 				16,
 		),
@@ -199,7 +211,7 @@ func simpleStringArgEvent(t testing.TB, irProg *ir.Program) []byte {
 	}
 	dataItem0 := output.DataItemHeader{
 		Type:    uint32(eventType.GetID()),
-		Length:  17,
+		Length:  33,
 		Address: 0,
 	}
 	dataItem1 := output.DataItemHeader{
@@ -213,7 +225,11 @@ func simpleStringArgEvent(t testing.TB, irProg *ir.Program) []byte {
 	item = append(item, unsafe.Slice(
 		(*byte)(unsafe.Pointer(&dataItem0)), unsafe.Sizeof(dataItem0))...,
 	)
-	item = append(item, 1) // bitset
+	item = append(item, 3) // bitset: bit 0 (argument) and bit 1 (template_segment) set
+	// First expression (argument) at offset 1
+	item = binary.NativeEndian.AppendUint64(item, 0xdeadbeef)
+	item = binary.NativeEndian.AppendUint64(item, 16)
+	// Second expression (template_segment) at offset 17
 	item = binary.NativeEndian.AppendUint64(item, 0xdeadbeef)
 	item = binary.NativeEndian.AppendUint64(item, 16)
 	item = append(item, 0, 0, 0, 0, 0, 0, 0) // padding
@@ -254,8 +270,8 @@ func simpleMapArgEvent(t testing.TB, irProg *ir.Program) []byte {
 	)
 
 	require.NotNil(t, eventType)
-	// Expect exactly one expression for parameter 'm'
-	require.NotEmpty(t, eventType.Expressions)
+	// Expect two expressions: argument and template_segment
+	require.GreaterOrEqual(t, len(eventType.Expressions), 2)
 	paramType := eventType.Expressions[0].Expression.Type
 	var ok bool
 	mapParamType, ok = paramType.(*ir.GoMapType)
@@ -299,14 +315,18 @@ func simpleMapArgEvent(t testing.TB, irProg *ir.Program) []byte {
 		strAddr     = uint64(0x300000003)
 	)
 
-	// Build root data item (presence bitset + pointer to header)
+	// Build root data item (presence bitset + pointers to header)
 	rootData := make([]byte, rootLen)
-	// Set presence bit for first expression
+	// Set presence bits for both expressions (bit 0 for argument, bit 1 for template_segment)
 	if eventType.PresenceBitsetSize > 0 {
-		rootData[0] = 1
+		rootData[0] = 3 // bits 0 and 1 set
 	}
+	// First expression (argument) at offset 1
 	ptrOff := int(eventType.Expressions[0].Offset)
 	binary.NativeEndian.PutUint64(rootData[ptrOff:ptrOff+8], headerAddr)
+	// Second expression (template_segment) at offset 9
+	templatePtrOff := int(eventType.Expressions[1].Offset)
+	binary.NativeEndian.PutUint64(rootData[templatePtrOff:templatePtrOff+8], headerAddr)
 
 	// Build header bytes
 	headerData := make([]byte, headerLen)
@@ -503,11 +523,16 @@ func simpleBigMapArgEvent(t testing.TB, irProg *ir.Program) []byte {
 	)
 
 	rootData := make([]byte, rootLen)
+	// Set presence bits for both expressions (bit 0 for argument, bit 1 for template_segment)
 	if eventType.PresenceBitsetSize > 0 {
-		rootData[0] = 1
+		rootData[0] = 3 // bits 0 and 1 set
 	}
+	// First expression (argument) at offset 1
 	ptrOff := int(eventType.Expressions[0].Offset)
 	binary.NativeEndian.PutUint64(rootData[ptrOff:ptrOff+8], headerAddr)
+	// Second expression (template_segment) at offset 9
+	templatePtrOff := int(eventType.Expressions[1].Offset)
+	binary.NativeEndian.PutUint64(rootData[templatePtrOff:templatePtrOff+8], headerAddr)
 
 	headerData := make([]byte, headerLen)
 	binary.NativeEndian.PutUint64(headerData[countOff:countOff+8], 1)
@@ -620,8 +645,9 @@ func simplePointerChainArgEvent(t testing.TB, irProg *ir.Program) []byte {
 	eventType := events[0].Type
 	rootLen := int(eventType.GetByteSize())
 	rootData := make([]byte, rootLen)
+	// Set presence bits for both expressions (bit 0 for argument, bit 1 for template_segment)
 	if eventType.PresenceBitsetSize > 0 {
-		rootData[0] = 1
+		rootData[0] = 3 // bits 0 and 1 set
 	}
 	// Build a fully captured pointer chain *****int → int(17)
 	argType := eventType.Expressions[0].Expression.Type
@@ -645,9 +671,12 @@ func simplePointerChainArgEvent(t testing.TB, irProg *ir.Program) []byte {
 		addr4 = uint64(0xa0000004)
 		addr5 = uint64(0xa0000005)
 	)
-	// Root data contains address of first pointer
+	// First expression (argument) at offset 1: address of first pointer
 	off := int(eventType.Expressions[0].Offset)
 	binary.NativeEndian.PutUint64(rootData[off:off+8], addr1)
+	// Second expression (template_segment) at offset 9: same address
+	templateOff := int(eventType.Expressions[1].Offset)
+	binary.NativeEndian.PutUint64(rootData[templateOff:templateOff+8], addr1)
 
 	// Helper to build a pointer data item (8-byte address payload)
 	makePtrItem := func(tid ir.TypeID, addr uint64, pointsTo uint64) (hdr output.DataItemHeader, data []byte) {