package silifuzz.proto

Get desktop application:
View/edit binary Protocol Buffers messages

A union of all message types that can be sent via a binary log channel. NextID: 8

• string session_id = 5

  ID of the session this entry belongs to.

• optional google.protobuf.Timestamp timestamp = 6

  Event timestamp.

• oneof kind

  • logging.SessionStart session_start = 7

    Session start event.

  • SnapshotExecutionResult snapshot_execution_result = 1

    Result of executing a snapshot

  • google.protobuf.Any build_info = 3

    Build information of the producer binary.

  • logging.SessionSummary session_summary = 4

    Session summary.

Memory checksum status after the snapshot failed (if any).

(message has no fields)

Used in: RunnerOutput, SnapshotExecutionResult

• NOT_CHECKED = 0

  No checksum was present in the snapshot or the checksum was not computed.

• MATCH = 1

  The checksum matched.

• MISMATCH = 2

  The checksum did not match.

Corpus metadata.

Used in: logging.SessionStart, logging.SessionSummary

• string version = 1

  Opaque version identifier.

Describes a specific endstate of executing a snapshot. NEXT ID: 6

Used in: PlayerResult, Snapshot

• optional Endpoint endpoint = 1

  Expected execution endpoint that defines this EndState.

  semantically required

• optional RegisterState registers = 2

  The expected state of the registers to exist at `endpoint`.

  semantically required

• repeated MemoryBytes memory_bytes = 3

  The expected memory state to exist at `endpoint`. Only differences from the starting state need to be mentioned here. Same constraints as for Snapshot.memory_bytes below wrt Snapshot.mappings.

  can be missing

• optional uint64 platforms = 4

  Set of platforms for which we've observed this EndState to occur for this snapshot. Empty set means that this EndState is provisional and can be removed once a real one is observed. The representation is a bit vector where PlatformId enum values are the bit indexes -- more compact than `repeated PlatformId` as the number of PlatformId values grows and assuming most end-states are the same for all platforms, so normally this will have all bits set. Make it repeated if we run out of bits in one int64.

  can be missing

• optional bytes register_checksum = 5

  Summary information of registers that are not fully recorded at the end of snapshot execution. This is serialized from a RegisterChecksum struct for the same architecture as the snapshot.

  can be missing

Describes an execution endpoint of a snapshot.

Used in: EndState

• oneof event

  Endpoint is the first occurence of the given event.

  • uint64 instruction_address = 1

    Event is reaching this instruction address.

  • Endpoint.Signal signal = 2

    Event is occurrence of a signal matching this description.

A more specific cause of the signal.

Used in: Signal

• UNDEFINED_SIG_CAUSE = 0

• GENERIC_SIG_CAUSE = 1

  for SIG_TRAP, SIG_FPE, SIG_ILL, or SIG_BUS

• SEGV_CANT_EXEC = 2

  for SIG_SEGV

• SEGV_CANT_WRITE = 3

  for SIG_SEGV

• SEGV_CANT_READ = 4

  for SIG_SEGV

• SEGV_OVERFLOW = 5

  for SIG_SEGV

• SEGV_GENERAL_PROTECTION = 6

  for SIG_SEGV

Supported signals that could be an endpoint. Note that all these singlas fill-in siginfo_t::si_addr.

Used in: Signal

• UNDEFINED_SIG_NUM = 0

• SIG_SEGV = 1

  SIGSEGV

• SIG_TRAP = 2

  SIGTRAP

• SIG_FPE = 3

  SIGFPE

• SIG_ILL = 4

  SIGILL

• SIG_BUS = 5

  SIGBUS

Describes a signal that snapshot's execution causes.

Used in: Endpoint

• optional SigNum sig_num = 1

  The signal.

  semantically required

• optional SigCause sig_cause = 2

  Cause of sig_num.

  semantically required

• optional uint64 sig_address = 3

  The siginfo_t::si_addr value: the address that causes the signal. Might need to become semantically optional if add support for signals that do not fill si_addr.

  semantically required

• optional uint64 sig_instruction_address = 4

  Value of the instruction address aka pointer when the signal occured. Might be the same as sig_address or not.

  semantically required

• optional string hostname = 1

  The hostname of the machine the test ran on.

• optional string platform = 2

  The platform the test generated instructions for. This may not be the same as the actual platform of the machine.

• optional string version = 3

  The version of hashtest that was run.

• optional HashTestResult.Status status = 4

  Is this machine good or bad, or did something go wrong trying to test it?

• optional google.protobuf.Timestamp testing_started = 5

  The beginning and end of the testing period.

• optional google.protobuf.Timestamp testing_ended = 6

• optional uint64 tests_run = 7

  Test statistics.

• optional uint64 tests_failed = 8

• repeated uint32 tested_cpus = 9

  CPU statistics.

• repeated uint32 suspected_cpus = 10

Used in: HashTestResult

• UNINITIALIZED = 0

  This should never occur, included so we absolutely notice a missing or mangled message.

• OK = 1

  The test completed successfully.

• FAILED = 2

  Data corruption was detected.

• PLATFORM_NOT_SUPPORTED = 3

  This particular CPU platform is currently not supported.

Describes a single contiguous range of byte values in memory.

Used in: EndState, Snapshot

• optional uint64 start_address = 1

  Where `byte_values` start.

  semantically required

• optional bytes byte_values = 2

  The memory byte values to exist at start_address. This may represent data or instructions.

  semantically required

Describes a single contiguous page-aligned memory mapping.

Used in: Snapshot, SnapshotSummary

• optional uint64 start_address = 1

  Start address and size of this mapping that define the [start_address, start_address + num_bytes) address range. Both values must be multiples of the page size.

  semantically required

• optional uint64 num_bytes = 2

  semantically required

• optional int32 permissions = 3

  Permissions to be set on the address range: an | of PermissionBits.

  semantically required

Bits for the possible permissions on memory to be binary-or-ed.

• READABLE = 1

• WRITABLE = 2

• EXECUTABLE = 4

Identifiers for all possible platform microarchitectures we run snapshots on. Grow or subdivide further if there are new machine types we can run on or if there are further differences in CPU's behavior.

• UNDEFINED_PLATFORM_ID = 0

• INTEL_SKYLAKE = 1

• INTEL_HASWELL = 2

• INTEL_BROADWELL = 3

• INTEL_IVYBRIDGE = 4

• INTEL_CASCADELAKE = 5

• AMD_ROME = 6

• INTEL_ICELAKE = 7

• AMD_MILAN = 8

• INTEL_SAPPHIRERAPIDS = 9

• AMD_GENOA = 10

• INTEL_COFFEELAKE = 11

• INTEL_ALDERLAKE = 12

• ARM_NEOVERSE_N1 = 13

• AMPERE_ONE = 14

• INTEL_EMERALDRAPIDS = 15

• AMD_RYZEN_V3000 = 17

• RESERVED_16 = 16

• RESERVED_18 = 18

• RESERVED_19 = 19

• RESERVED_20 = 20

• RESERVED_21 = 21

• RESERVED_22 = 22

• RESERVED_23 = 23

• RESERVED_24 = 24

• RESERVED_25 = 25

• RESERVED_26 = 26

• RESERVED_27 = 27

• RESERVED_28 = 28

• RESERVED_29 = 29

• RESERVED_30 = 30

• RESERVED_31 = 31

• RESERVED_32 = 32

• RESERVED_33 = 33

• RESERVED_34 = 34

• RESERVED_35 = 35

• RESERVED_36 = 36

• RESERVED_37 = 37

• RESERVED_38 = 38

• RESERVED_39 = 39

• RESERVED_40 = 40

  Ids up to 40 are reserved for proprietary platforms.

• INTEL_GRANITERAPIDS = 41

• AMD_SIENA = 42

• ARM_NEOVERSE_V2 = 43

• AMD_TURIN = 44

• ARM_NEOVERSE_N3 = 45

The proto defintion matches the class definition of Player::Result. Please refer to Player::Result for details.

Used in: SnapshotExecutionResult

• optional PlayerResult.Outcome outcome = 1

  semantically required

• optional int32 end_state_index = 2

  Index of the (partially) matched element of Snapshot::expected_end_states(). Maybe missing depending on outcome.

• optional EndState actual_end_state = 3

  Actual end-state reached. This may be missing depending on outcome, please refer to Player::Result for gory details. Inside the player, we may not store the actual endstate if a snapshot ends as expected because we can use an index to one of the expected endstates. Outside the player, we may store the full endstate regardless because we do not have access to the expected endstates.

• optional google.protobuf.Duration cpu_usage = 4

  CPU time used in playing the snapshot. This is an overestimate with unavoidable overheads in the player.

• optional int64 cpu_id = 5

  CPU number where the snapshot ran.

Snapshot playback outcome code.

Used in: PlayerResult

• AS_EXPECTED = 0

• PLATFORM_MISMATCH = 1

• MEMORY_MISMATCH = 2

• REGISTER_STATE_MISMATCH = 3

• ENDPOINT_MISMATCH = 4

• EXECUTION_RUNAWAY = 5

• EXECUTION_MISBEHAVE = 6

Describes the state of CPU registers. This is available from silifuzz/util/ucontext/ucontext.h

Used in: EndState, Snapshot

• optional bytes gregs = 1

  Serialized bytes of the GRegSet struct.

  semantically required

• optional bytes fpregs = 2

  Serialized bytes of the FPRegSet struct.

  semantically required

RunnerOutput represents the result of a single runner execution.

• optional RunnerOutput.ExecutionResult execution_result = 1

  Semantically required.

• optional SnapshotExecutionResult failed_snapshot_execution = 2

  An optional failed snapshot execution result.

• optional ChecksumStatus.Enum postfailure_checksum_status = 3

  Memory checksum status after the snapshot failed (if any).

Overall execution result.

Used in: RunnerOutput

• optional ExecutionResult.StatusCode code = 1

  Status code for this execution. Semantically required.

• optional string msg = 2

  An optional human-readable message.

Used in: ExecutionResult

• INTERNAL_ERROR = 0

• OK = 1

  Runner executed successfully.

• UNHANDLED_SIGNAL = 2

  Runner crashed due to an unhandled signal.

• MMAP_FAILED = 3

  Runner failed to mmap a memory mapping.

• OVERLAPPING_MAPPINGS = 4

  Runner detected overlapping memory mappings.

• INITIAL_CHECKSUM_MISMATCH = 5

  Runner detected a checksum mismatch before running any tests.

• SNAPSHOT_FAILED = 6

  One of the snapshots failed to execute. Inspect `failed_snapshot_execution` for details.

Proto representation of a snapshot: instructions and the necessary data for execution of some relatively short snippet of binary code (single threaded user-space code) with a well-defined end state. IMPORTANT: In C++ code work with the Snapshot class from silifuzz/common/snapshot.h, not with this proto. We envision adding more fields to describe useful information about the snapshot to help analyze and mutate it (such as disassembly). TBD: Do it via additional fields here or via new message(s) that include this one -- it may be renamed to SnapshotToPlay. NEXT ID: 10

• optional string id = 6

  Snapshot identifier. The identifier is a printable string e.g. hex of an MD5 hash that identifies a snapshot instance and is globally unique. Possible ways to produce an id include MD5(Snapshot), NewGlobalID or UUID. A special value "has_not_been_set" has been designated for snapshots that have not had any ID assigned.

  semantically required.

• optional Snapshot.Architecture architecture = 1

  Architecture this snapshot is meant for, i.e. its target architecture.

  semantically required

• optional SnapshotMetadata metadata = 8

  Metadata about this snapshot. Not necessary for playing or transforming the snapshot, so could be stripped and/or stored separately as needed.

  can be missing

• repeated MemoryMapping memory_mappings = 2

  All the memory mappings that exist at the start of the snapshot. Must be disjoint.

  >=1 is semantically required

• repeated MemoryMapping negative_memory_mappings = 7

  All the memory mapping permissions that must not exist during playback of the snapshot. I.e. the specified address ranges must not have the specified permissions (but can have other permissions) if mapped at all. These are necessary to guarantee reproduction of a SIGSEGV Endpoint. Must be disjoint and not conflict with memory_mappings.

  can be missing

• repeated MemoryBytes memory_bytes = 3

  All the memory state that exists at the start of the snapshot. Must be disjoint. Each entry must be inside the union of the memory_mappings, but any of the memory_mappings elements does not need to be fully written by the union of memory_bytes, but the following must hold: IMPORTANT: memory_bytes must cover all the areas that the snapshot will a) write into or b) read-from and then depend on for its outcome. Note that snapshot parsing code can't check for these conditions. Having such regions in memory_mappings with appropriate permissions is insufficient. This is because without a memory_bytes specification, the values of those bytes at the start of snapshot's execution can be arbitraty. So for case b) this can lead to the snapshot arriving at a different end-state. While for case a) it's possible that those bytes will already have the values that snapshot is going to write in a given execution of the snapshot. Hence if we were recording what snapshot did based on that run, we'd incorrectly not notice those writes, while on a later run they would manifest as unexpected changes. An easy way to satisfy these conditions is to make memory_bytes cover all of memory_mappings with r or w permissions.

  >=1 is semantically required

• optional RegisterState registers = 4

  The state of the registers at the start of the snapshot.

  semantically required

• repeated EndState expected_end_states = 5

  The possible expected end-states of executing the snapshot.

  >=1 is semantically required

• repeated SnapshotTraceData trace_data = 9

  Trace data for the snapshot.

  can be missing

Supported architectures of snapshots.

Used in: Snapshot

• UNDEFINED_ARCH = 0

• X86_64 = 1

• AARCH64 = 2

A proto to store snapshot execution result identified by a snapshot ID and a play result. NextID: 6

Used in: BinaryLogEntry, RunnerOutput

• optional string snapshot_id = 1

  ID of the snapshot.

  semantically required.

• optional string hostname = 4

  Machine hostname where the snapshot was executed. Should not contain the domain name part (e.g. just abc123)

  semantically required

• optional PlayerResult player_result = 2

  Execution result from Player.

• optional google.protobuf.Timestamp time = 3

  Time when this result was recorded. NOTE that this field must be preserved for compatibility with older text-formatted results. TODO(ksteuck): Revisit once the old data has gone beyond the analysis horizon (Q2 2025-ish).

• optional ChecksumStatus.Enum postfailure_checksum_status = 5

  Memory checksum status after the snapshot failed (if any).

A convenience wrapper for Snapshot.id useful for data processing pipelines.

• optional string value = 1

  Same as Snapshot.id

  semantically required

Metadata about a Snapshot. We use an "enum selector plus appropriately optional detail fields" format instead of a hierarchy of one_of-s because this proto is not for human or wide code consumption and for many snapshot origin types there are no extra details, so the one_of messages would be empty. NEXT ID: 9

Used in: Snapshot

• optional SnapshotMetadata.Origin origin = 2

  semantically required

• optional string origin_string = 8

  Free-form origin.

How snapshot originated. NEXT ID: 14

Used in: SnapshotMetadata

• UNDEFINED_ORIGIN = 0

  When origin is unknown or unimportant, e.g. snapshot was made by some test-generation logic.

• IFUZZ_ORIGIN = 2

  Snapshot was made by ifuzz.

• UNICORN_FUZZING_ORIGIN = 3

  Snapshot was made by fuzzing {Unicorn,Bochs,etc} with libFuzzer.

• BOCHS_FUZZING_ORIGIN = 5

• XED_FUZZING_ORIGIN = 6

• GEM5_FUZZING_ORIGIN = 7

• USE_STRING_ORIGIN = 13

  Special value to direct the consumers to use SnapshotMetadata.origin_string value instead.

Describes a single Snapshot for the purposes of sharding. See PartitionCorpus() for details.

• optional string id = 1

  Id of the snapshot.

• repeated MemoryMapping memory_mappings = 2

  Snapshot memory mappings.

• optional int32 sort_key = 3

  Opaque sort key.

Metadata obtained from tracing a snapshot.

Used in: Snapshot

• optional uint64 platforms = 1

  Set of platforms for which we've observed this trace. The representation is a bit vector is the same as EndState.platforms

  semantically required

• optional uint64 num_instructions = 2

  Number of instructions executed before the Snapshot was stopped.

• optional string human_readable_disassembly = 3

  Human-readable trace of all instructions executed before reaching some terminal state. The exact format varies between architectures and versions. Do not rely on this field to determine the dynamic length of the Snapshot, use `num_instructions` instead.