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.thread.proto; 17 18import "pw_tokenizer/proto/options.proto"; 19 20option java_package = "pw.thread.proto"; 21option java_outer_classname = "Thread"; 22 23message ThreadState { 24 enum Enum { 25 // Thread state is invalid or cannot be expressed by this enum. 26 UNKNOWN = 0; 27 // Interrupt handling is often done on a stack that isn't associated with a 28 // true RTOS thread. This state indicates the provided thread info is for an 29 // interrupt handler. 30 INTERRUPT_HANDLER = 1; 31 // This is the currently active thread as marked by the RTOS. In crashes in 32 // interrupt contexts, this isn’t necessarily the thread that crashed. 33 RUNNING = 2; 34 // Thread is ready to run, but isn’t currently running. 35 READY = 3; 36 // The thread is not ready to run, and will not be ready to run until it is 37 // explicitly resumed. 38 SUSPENDED = 4; 39 // The thread is waiting on something before it can run again. 40 BLOCKED = 5; 41 // The thread is either not yet initialized, or has terminated. In other 42 // words, this thread is a suspended thread that cannot be unsuspended. 43 INACTIVE = 6; 44 } 45} 46 47message Thread { 48 // Thread names must be unique; this allows extensions of Snapshot to augment 49 // threads with additional data. This should either be human readable text, or 50 // tokenized data (e.g. base-64 encoded or binary data). 51 bytes name = 1 [(tokenizer.format) = TOKENIZATION_OPTIONAL]; 52 53 // This field has been deprecatdin favor of using the state enum to report 54 // RUNNING or INTERRUPT_CONTEXT to mark them as active. 55 // 56 // Whether or not this thread is the thread is the currently active context 57 // at the time of capture. For multi-thread dumps, this field should only be 58 // set on ONE thread. 59 bool active = 2 [deprecated = true]; 60 61 // A summarized thread state. RTOS-specific extensions of the Thread message 62 // may provide more specific thread state information. 63 ThreadState.Enum state = 3; 64 65 // Contents of a stack trace. It is expected that this stack is pre-walked, 66 // and contains addresses. Most recent stack events are at the beginning of 67 // the captured stack trace. 68 repeated uint64 raw_backtrace = 4; 69 70 // Results of symbolizing stack_entries. This is usually not provided by the 71 // device, but instead by server/host side processing. 72 repeated string symbolized_backtrace = 5; 73 74 // This should contain the raw contents of the thread's stack. This might not 75 // match stack_size. It can be larger due to a stack overflow, or smaller due 76 // to the implementation deciding to only capture a portion of the stack. 77 // Partial stack captures are typically a result of storage/memory 78 // limitations. 79 bytes raw_stack = 6; 80 81 // The address this thread's stack pointer began at. For descending stacks, 82 // this is the highest address of the stack bounds. For ascending stacks, this 83 // is the lowest address of the stack bounds. 84 optional uint64 stack_start_pointer = 7; 85 86 // The furthest permitted address from where this thread's stack pointer 87 // began. For descending stacks, this is the lowest address of the stack 88 // bounds. For ascending stacks, this is the highest address of the stack 89 // bounds. 90 optional uint64 stack_end_pointer = 8; 91 92 // The current stack pointer of this thread. 93 optional uint64 stack_pointer = 9; 94 95 // CPU usage info. This is the percentage of CPU time the thread has been 96 // active in hundredths of a percent. (e.g. 5.00% = 500u) 97 optional uint32 cpu_usage_hundredths = 10; 98 99 // The address of highest estimated currently used in the thread stack. 100 // Percentage of bytes used can be calculated by: 101 // (stack_estimate_max_addr-stack_start_pointer) / 102 // (stack_end_pointer-stack_start_pointer) * 100% 103 optional uint64 stack_pointer_est_peak = 11; 104} 105 106// This message overlays the pw.snapshot.Snapshot proto. It's valid to encode 107// this message to the same sink that a Snapshot proto is being written to. 108message SnapshotThreadInfo { 109 repeated pw.thread.proto.Thread threads = 18; 110} 111