github.com/google/pprof v0.0.0-20200708004538-1a94d8640e99: profile.Mapping

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify github.com/google/pprof/profile.Mapping in pkg:golang/github.com/google/pprof@v0.0.0-20200708004538-1a94d8640e99
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/google/pprof@v0.0.0-20200708004538-1a94d8640e99
Demonstrate these symbols/APIs:
  - github.com/google/pprof/profile.Mapping
Required runtime conditions:
  - ecosystem: golang
  - language: go
  - packageManager: go@1.26.6
  - runtime: go@1.26.6

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:cedac0b613d74b9c71b2dcd328d0f3252404bd0927f7042d65894e28b26dbbf0","contract":["profile.Mapping defines a memory mapping region with address bounds, offset, file path, build ID, and symbolization flags","Mapping.Unsymbolizable detects system and virtual mapping regions such as vdso and vsyscall that cannot be symbolized","profile.CheckValid enforces that mappings have non-zero IDs without duplicates and locations reference declared mappings","Profile serialization and parsing preserves profile.Mapping fields and location mapping references across round trips"],"goal":"verify github.com/google/pprof/profile.Mapping in pkg:golang/github.com/google/pprof@v0.0.0-20200708004538-1a94d8640e99","kind":"HOW","packages":["pkg:golang/github.com/google/pprof@v0.0.0-20200708004538-1a94d8640e99"],"schemaVersion":1,"symbols":["github.com/google/pprof/profile.Mapping"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/google/pprof@v0.0.0-20200708004538-1a94d8640e99"],"schemaVersion":1,"subject":"pkg:golang/github.com/google/pprof@v0.0.0-20200708004538-1a94d8640e99","symbols":["github.com/google/pprof/profile.Mapping"],"verifierAdapter":"golang@1"}

module sample

go 1.25.0

require github.com/google/pprof v0.0.0-20200708004538-1a94d8640e99

github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
github.com/google/pprof v0.0.0-20200708004538-1a94d8640e99 h1:Ak8CrdlwwXwAZxzS66vgPt4U8yUZX7JwLvVR58FN5jM=
github.com/google/pprof v0.0.0-20200708004538-1a94d8640e99/go.mod h1:ZgVRPoUq/hfqzAqh7sHMqb3I9Rq5C59dIz2SbBwJ4eM=
github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
golang.org/x/sys v0.0.0-20191204072324-ce4227a45e2e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=

package sample

import (
	"bytes"
	"fmt"
	"io"

	"github.com/google/pprof/profile"
)

// NewMapping creates a profile.Mapping with address bounds and symbolization flags.
func NewMapping(id uint64, start, limit, offset uint64, file, buildID string) *profile.Mapping {
	return &profile.Mapping{
		ID:              id,
		Start:           start,
		Limit:           limit,
		Offset:          offset,
		File:            file,
		BuildID:         buildID,
		HasFunctions:    true,
		HasFilenames:    true,
		HasLineNumbers:  true,
		HasInlineFrames: true,
	}
}

// CreateProfileWithMapping builds a valid minimal profile containing the provided mapping and location.
func CreateProfileWithMapping(m *profile.Mapping) *profile.Profile {
	loc := &profile.Location{
		ID:      1,
		Mapping: m,
		Address: m.Start + 0x10,
	}
	return &profile.Profile{
		SampleType: []*profile.ValueType{
			{Type: "samples", Unit: "count"},
		},
		PeriodType: &profile.ValueType{Type: "cpu", Unit: "nanoseconds"},
		Period:     10000000,
		Mapping:    []*profile.Mapping{m},
		Location:   []*profile.Location{loc},
		Sample: []*profile.Sample{
			{
				Location: []*profile.Location{loc},
				Value:    []int64{1},
			},
		},
	}
}

// ParseProcMapsWrapper parses a memory map formatted as /proc/self/maps.
func ParseProcMapsWrapper(rd io.Reader) ([]*profile.Mapping, error) {
	return profile.ParseProcMaps(rd)
}

// RoundTripProfile serializes a profile to gzip protobuf bytes and parses it back.
func RoundTripProfile(p *profile.Profile) (*profile.Profile, error) {
	var buf bytes.Buffer
	if err := p.Write(&buf); err != nil {
		return nil, fmt.Errorf("failed to write profile: %w", err)
	}
	parsed, err := profile.Parse(&buf)
	if err != nil {
		return nil, fmt.Errorf("failed to parse profile: %w", err)
	}
	return parsed, nil
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/google/pprof/profile.Mapping in pkg:golang/github.com/google/pprof@v0.0.0-20200708004538-1a94d8640e99",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/google/pprof@v0.0.0-20200708004538-1a94d8640e99"
  ],
  "symbols": [
    "github.com/google/pprof/profile.Mapping"
  ],
  "runtimeConditions": {
    "ecosystem": "golang",
    "language": "go",
    "packageManager": "go@1.26.6",
    "runtime": "go@1.26.6"
  }
}

package main

import (
	"fmt"
	"os"

	"github.com/google/pprof/profile"
	"sample"
)

func main() {
	// Assertion 1: profile.Mapping defines a memory mapping region with address bounds, offset, file path, build ID, and symbolization flags
	m := sample.NewMapping(1, 0x400000, 0x401000, 0, "/bin/testapp", "build-id-1234")
	if m.ID != 1 || m.Start != 0x400000 || m.Limit != 0x401000 || m.Offset != 0 {
		fmt.Fprintf(os.Stderr, "mapping address bounds mismatch: %+v\n", m)
		os.Exit(1)
	}
	if m.File != "/bin/testapp" || m.BuildID != "build-id-1234" {
		fmt.Fprintf(os.Stderr, "mapping metadata mismatch: file=%s buildID=%s\n", m.File, m.BuildID)
		os.Exit(1)
	}
	if !m.HasFunctions || !m.HasFilenames || !m.HasLineNumbers || !m.HasInlineFrames {
		fmt.Fprintf(os.Stderr, "mapping symbolization flags mismatch: %+v\n", m)
		os.Exit(1)
	}

	// Assertion 2: Mapping.Unsymbolizable detects system and virtual mapping regions such as vdso and vsyscall that cannot be symbolized
	if m.Unsymbolizable() {
		fmt.Fprintf(os.Stderr, "expected regular binary mapping to be symbolizable\n")
		os.Exit(1)
	}
	vdsoMapping := &profile.Mapping{
		ID:   2,
		File: "[vdso]",
	}
	if !vdsoMapping.Unsymbolizable() {
		fmt.Fprintf(os.Stderr, "expected [vdso] mapping to be unsymbolizable\n")
		os.Exit(1)
	}
	linuxVdsoMapping := &profile.Mapping{
		ID:   3,
		File: "linux-vdso.so.1",
	}
	if !linuxVdsoMapping.Unsymbolizable() {
		fmt.Fprintf(os.Stderr, "expected linux-vdso mapping to be unsymbolizable\n")
		os.Exit(1)
	}

	// Assertion 3: profile.CheckValid enforces that mappings have non-zero IDs without duplicates and locations reference declared mappings
	p := sample.CreateProfileWithMapping(m)
	if err := p.CheckValid(); err != nil {
		fmt.Fprintf(os.Stderr, "valid profile CheckValid failed: %v\n", err)
		os.Exit(1)
	}

	invalidZeroID := &profile.Mapping{
		ID:    0,
		Start: 0x500000,
		Limit: 0x501000,
	}
	pZeroID := &profile.Profile{
		SampleType: []*profile.ValueType{{Type: "samples", Unit: "count"}},
		Mapping:    []*profile.Mapping{invalidZeroID},
	}
	if err := pZeroID.CheckValid(); err == nil {
		fmt.Fprintf(os.Stderr, "expected CheckValid error for mapping ID=0, got nil\n")
		os.Exit(1)
	}

	dupMapping1 := &profile.Mapping{ID: 5, Start: 0x600000, Limit: 0x601000}
	dupMapping2 := &profile.Mapping{ID: 5, Start: 0x700000, Limit: 0x701000}
	pDup := &profile.Profile{
		SampleType: []*profile.ValueType{{Type: "samples", Unit: "count"}},
		Mapping:    []*profile.Mapping{dupMapping1, dupMapping2},
	}
	if err := pDup.CheckValid(); err == nil {
		fmt.Fprintf(os.Stderr, "expected CheckValid error for duplicate mapping IDs, got nil\n")
		os.Exit(1)
	}

	undeclaredMapping := &profile.Mapping{ID: 99, Start: 0x800000, Limit: 0x801000}
	locUndeclared := &profile.Location{ID: 2, Mapping: undeclaredMapping}
	pUndeclared := &profile.Profile{
		SampleType: []*profile.ValueType{{Type: "samples", Unit: "count"}},
		Mapping:    []*profile.Mapping{m},
		Location:   []*profile.Location{locUndeclared},
	}
	if err := pUndeclared.CheckValid(); err == nil {
		fmt.Fprintf(os.Stderr, "expected CheckValid error for undeclared location mapping, got nil\n")
		os.Exit(1)
	}

	// Assertion 4: Profile serialization and parsing preserves profile.Mapping fields and location mapping references across round trips
	rtProfile, err := sample.RoundTripProfile(p)
	if err != nil {
		fmt.Fprintf(os.Stderr, "round trip serialization failed: %v\n", err)
		os.Exit(1)
	}
	if err := rtProfile.CheckValid(); err != nil {
		fmt.Fprintf(os.Stderr, "round trip profile CheckValid failed: %v\n", err)
		os.Exit(1)
	}
	if len(rtProfile.Mapping) != 1 {
		fmt.Fprintf(os.Stderr, "round trip mapping count mismatch: got %d, want 1\n", len(rtProfile.Mapping))
		os.Exit(1)
	}
	rtM := rtProfile.Mapping[0]
	if rtM.ID != m.ID || rtM.Start != m.Start || rtM.Limit != m.Limit || rtM.Offset != m.Offset {
		fmt.Fprintf(os.Stderr, "round trip mapping address mismatch\n")
		os.Exit(1)
	}
	if rtM.File != m.File || rtM.BuildID != m.BuildID {
		fmt.Fprintf(os.Stderr, "round trip mapping metadata mismatch\n")
		os.Exit(1)
	}
	if len(rtProfile.Location) != 1 || rtProfile.Location[0].Mapping != rtM {
		fmt.Fprintf(os.Stderr, "round trip location mapping reference mismatch\n")
		os.Exit(1)
	}

	fmt.Println("All profile.Mapping contract assertions passed.")
}