pw_snapshot/pw_snapshot_protos/snapshot_metadata.proto

// Copyright 2021 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
syntax = "proto3";

package pw.snapshot;

import "pw_tokenizer/proto/options.proto";

option java_package = "pw.snapshot.proto";
option java_outer_classname = "Snapshot";

message CpuArchitecture {
  enum Enum {
    UNKNOWN = 0;
    ARMV6M = 1;
    ARMV7M = 2;
    ARMV8M = 3;
  }
}

message Metadata {
  // A relatively unique descriptive reason for what triggered the snapshot
  // capture. This should either be human readable text, or tokenized data
  // (e.g. base-64 encoded or binary data).
  //
  // Examples:
  //   Null-pointer dereference
  //   [main.cc:22] True is not false!
  //   STACK_OVERFLOW
  bytes reason = 1 [(tokenizer.format) = TOKENIZATION_OPTIONAL];

  // Whether or not the snapshot was captured due to a crash of some kind.
  bool fatal = 2;

  // Project name to assist in identifying where to redirect this snapshot. A
  // single project might have multiple devices that can produce snapshots.
  bytes project_name = 3 [(tokenizer.format) = TOKENIZATION_OPTIONAL];

  // Version characters must be alphanumeric, punctuation, and space. This
  // string is case-sensitive. This should always be human readable text, and
  // does not support tokenization by design. If this field was tokenized, it's
  // possible that the token could be lost (e.g. generated by a local developer
  // build and not uploaded anywhere) and a firmware version running on a device
  // in the field would be left entirely unidentifiable.
  //
  // Examples:
  //   "codename-local-[build_id]"
  //   "codename-release-193"
  string software_version = 4;

  // UUID associated with the build for the software version.
  bytes software_build_uuid = 5;

  // String containing the specific device name. This should be as specific as
  // possible, detailing hardware revision, and distinguishing different cores
  // in a multi-core device. Snapshots aggregated as related_snapshots should
  // include information that distinguishes the source of the snapshot. This
  // should either be human readable text, or tokenized data.
  //
  // Examples:
  //   "propellerhat-evk"
  //   "gshoe-sensor-core-pvt"
  //   "alarm-clock-dsp-p1"
  bytes device_name = 6 [(tokenizer.format) = TOKENIZATION_OPTIONAL];

  // 128-bit UUID for this snapshot, used to help with de-duplication.
  bytes snapshot_uuid = 7;

  // The architecture of the CPU that generated this report.
  CpuArchitecture.Enum cpu_arch = 8;
}

// This message overlays the pw.snapshot.Snapshot proto. It's valid to encode
// this message to the same sink that a Snapshot proto is being written to.
message SnapshotBasicInfo {
  Metadata metadata = 16;
  map<string, string> tags = 17;
}