1// Copyright 2021 The Pigweed Authors 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); you may not 4// use this file except in compliance with the License. You may obtain a copy of 5// the License at 6// 7// https://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12// License for the specific language governing permissions and limitations under 13// the License. 14syntax = "proto3"; 15 16package pw.snapshot; 17 18option java_package = "pw.snapshot.proto"; 19option java_outer_classname = "Snapshot"; 20 21import "pw_chrono_protos/chrono.proto"; 22import "pw_cpu_exception_cortex_m_protos/cpu_state.proto"; 23import "pw_log/proto/log.proto"; 24import "pw_thread_protos/thread.proto"; 25import "pw_snapshot_metadata_proto/snapshot_metadata.proto"; 26 27// The Snapshot proto is a list that dictates field numbers that should 28// be used when serializing proto messages into a "Snapshot" that can be 29// ingested by Pigweed's upstream tooling. 30// 31// There are various field number ranges that are marked for "upstream" use, 32// and others that are marked for "pigweed users". This allows a user to 33// define a parallel proto that defines product-specific messages using mutually 34// exclusive field numbers: 35// 36// MySnapshot { 37// // Use a project-specific logging proto format. 38// repeated MyLogFormat = 8; 39// 40// // Pigweed's snapshot doesn't support my custom RTOS, so write that to 41// // a field number reserved for downstream projects. 42// MyCustomRtosInfo = 22; 43// } 44// 45// Writing both proto messages to the same proto encoder is valid because the 46// field nubmers are mutually exclusive. This prevents collisions that would 47// break a proto decode. The final message will have to be decoded twice; once 48// as a pw.snapshot.Snapshot and once as the project-specific message. 49message Snapshot { 50 repeated pw.log.LogEntry logs = 1; 51 52 // RESERVED FOR PIGWEED. These field numbers are reserved strictly for things 53 // that are very generally useful and high in count. Downstream projects may 54 // NOT write to these fields. 55 // Encodes to a single byte of tag overhead. 56 reserved 2 to 7; 57 58 // RESERVED FOR USERS. These field numbers should be used for writing 59 // project-specific proto messages that repeat in high quantity to reduce 60 // proto encoding overhead. Pigweed must not write to these fields. 61 // Encodes to a single byte of tag overhead. 62 reserved 8 to 15; 63 64 // Note: Proto tags 16-2047 encode with two bytes of overhead. 65 Metadata metadata = 16; 66 67 // Other data that should be highlighted in this crash. This field may have 68 // entries added to it during a decode. 69 map<string, string> tags = 17; 70 71 repeated pw.thread.proto.Thread threads = 18; 72 73 // If a device has multiple cores, it may be useful to collect an associated 74 // snapshot for attached cores when a snapshot collection is triggered on one 75 // core. By embedding one or more snapshots into a snapshot, the snapshots are 76 // considered associated. 77 repeated Snapshot related_snapshots = 19; 78 79 pw.cpu_exception.cortex_m.ArmV7mCpuState armv7m_cpu_state = 20; 80 81 // Platform-specific binary trace data region. Binary trace data is using 82 // pw_trace_tokenized buffer format for stored data. 83 bytes trace_data = 21; 84 85 // Timestamps that mark when this snapshot occurred. This field is repeated 86 // to accommodate wall-clock time, time since boot, and/or the raw system 87 // clock value. 88 repeated pw.chrono.TimePoint timestamps = 22; 89 90 // RESERVED FOR PIGWEED. Downstream projects may NOT write to these fields. 91 // Encodes to two bytes of tag overhead. 92 reserved 23 to 1031; 93 94 // RESERVED FOR USERS. Encodes to two or more bytes of tag overhead. 95 reserved 1032 to max; 96} 97