/*
 * Copyright (C) 2025 The Android Open Source Project
 *
 * 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
 *
 *      http://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 = "proto2";
package perfetto.protos;

// GenericKernelTaskStateEvent is the standard proto to capture thread state
// change events in a generic kernel implementation. This is mainly for the
// case where scheduler events are not directly supported in the kernel's
// tracing mechanism.
//
// By capturing these task state events Perfetto is able to infer higher-level
// events such as context switches and task waking events, providing as much
// parity as possible with established tracing frameworks such as
// Linux's ftrace.
message GenericKernelTaskStateEvent {
  // CPU in which the event occurred.
  // This field is only relevant with the TASK_STATE_RUNNING state. There is
  // no specific meaning to the cpu field in a non-running state event.
  optional int32 cpu = 1;
  // Command name for the thread.
  optional string comm = 2;
  // Thread id.
  optional int64 tid = 3;

  // TaskStateEnum represents the valid states of a thread.
  // These states are a generic representation of the actual thread state and
  // don't necessarily map one-to-one to the states the actual OS kernel
  // tracks internally.
  //
  // Note: Consecutive TASK_STATE_RUNNING states for the same TID is considered
  // an error resulting in potential data loss.
  enum TaskStateEnum {
    TASK_STATE_UNKNOWN = 0;
    TASK_STATE_CREATED = 1;
    TASK_STATE_RUNNABLE = 2;
    TASK_STATE_RUNNING = 3;
    TASK_STATE_INTERRUPTIBLE_SLEEP = 4;
    TASK_STATE_UNINTERRUPTIBLE_SLEEP = 5;
    TASK_STATE_STOPPED = 6;
    TASK_STATE_DEAD = 7;
    TASK_STATE_DESTROYED = 8;
  }
  // New state of the thread.
  optional TaskStateEnum state = 4;

  // Priority of the thread.
  // This value is OS agnostic and should only be interpreted based on the
  // kernel who emitted the message.
  optional int32 prio = 5;
}

// GenericKernelTaskRenameEvent is the standard proto to capture the renaming
// of a thread.
message GenericKernelTaskRenameEvent {
  // Thread id.
  optional int64 tid = 1;
  // New command name for the thread.
  optional string comm = 2;
}

