// 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.thread;

import "pw_tokenizer/proto/options.proto";

option java_package = "pw.thread.proto";
option java_outer_classname = "Thread";

message ThreadState {
  enum Enum {
    // Thread state is invalid or cannot be expressed by this enum.
    UNKNOWN = 0;
    // Interrupt handling is often done on a stack that isn't associated with a
    // true RTOS thread. This state indicates the provided thread info is for an
    // interrupt handler.
    INTERRUPT_HANDLER = 1;
    // This is the currently active thread as marked by the RTOS. In crashes in
    // interrupt contexts, this isn’t necessarily the thread that crashed.
    RUNNING = 2;
    // Thread is ready to run, but isn’t currently running.
    READY = 3;
    // The thread is not ready to run, and will not be ready to run until it is
    // explicitly resumed.
    SUSPENDED = 4;
    // The thread is waiting on something before it can run again.
    BLOCKED = 5;
    // The thread is either not yet initialized, or has terminated. In other
    // words, this thread is a suspended thread that cannot be unsuspended.
    INACTIVE = 6;
  }
}

message Thread {
  // Thread names must be unique; this allows extensions of Snapshot to augment
  // threads with additional data. This should either be human readable text, or
  // tokenized data (e.g. base-64 encoded or binary data).
  bytes name = 1 [(tokenizer.format) = TOKENIZATION_OPTIONAL];

  // Whether or not this thread is the thread is the currently active context
  // at the time of capture. For multi-thread dumps, this field should only be
  // set on ONE thread.
  //
  // Note: in interrupt contexts, the active thread may not be the thread that
  // is in the THREAD_STATE_RUNNING state.
  bool active = 2;

  // A summarized thread state. RTOS-specific extensions of the Thread message
  // may provide more specific thread state information.
  ThreadState.Enum state = 3;

  // Contents of a stack trace. It is expected that this stack is pre-walked,
  // and contains addresses. Most recent stack events are at the beginning of
  // the captured stack trace.
  repeated uint64 raw_backtrace = 4;

  // Results of symbolizing stack_entries. This is usually not provided by the
  // device, but instead by server/host side processing.
  repeated string symbolized_backtrace = 5;

  // This should contain the raw contents of the thread's stack. This might not
  // match stack_size. It can be larger due to a stack overflow, or smaller due
  // to the implementation deciding to only capture a portion of the stack.
  // Partial stack captures are typically a result of storage/memory
  // limitations.
  bytes raw_stack = 6;

  // The address this thread's stack pointer began at. For descending stacks,
  // this is the highest address of the stack bounds. For ascending stacks, this
  // is the lowest address of the stack bounds.
  optional uint64 stack_start_pointer = 7;

  // The furthest permitted address from where this thread's stack pointer
  // began. For descending stacks, this is the lowest address of the stack
  // bounds. For ascending stacks, this is the highest address of the stack
  // bounds.
  optional uint64 stack_end_pointer = 8;

  // The current stack pointer of this thread.
  optional uint64 stack_pointer = 9;

  // CPU usage info. This is the percentage of CPU time the thread has been
  // active in hundredths of a percent. (e.g. 5.00% = 500u)
  optional uint32 cpu_usage_hundredths = 10;

  // The address of highest estimated currently used in the thread stack.
  // Percentage of bytes used can be calculated by:
  // (stack_estimate_max_addr-stack_start_pointer) /
  // (stack_end_pointer-stack_start_pointer) * 100%
  optional uint64 stack_pointer_est_peak = 11;
}

// 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 SnapshotThreadInfo {
  repeated pw.thread.Thread threads = 18;
}