// @file sns_diag_sensor.proto
//
// @brief Defines standard message types to communicate with the
// diag sensor.
//
// @copyright
// Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.
//
// @details The diag sensor is used to select a data_type for diag logging
// and F3 msgs print on QXDM.
//
// ## Attribute Requirements:
// 1. SNS_STD_SENSOR_ATTRID_TYPE: "diag_sensor"
// 2. SNS_STD_SENSOR_ATTRID_API attribute contains "sns_diag_sensor.proto".
// 3. SNS_STD_SENSOR_ATTRID_STREAM_TYPE: SNS_STD_SENSOR_STREAM_TYPE_ON_CHANGE
//
// ## Processing Stream Requests:
// - SNS_DIAG_SENSOR_MSGID_SNS_DIAG_GET_CM_ACTIVE_CLIENT_REQ is used to query
// active client requests running on all client managers on a particular
// sensing hub instance.
// - SNS_DIAG_SENSOR_MSGID_SNS_DIAG_DEBUG_REQ is used to query debug information
//
// ## Publishing Stream Events:
// - SNS_DIAG_SENSOR_MSGID_SNS_DIAG_CM_ACTIVE_CLIENT_REQ_EVENT is used to
// publish an event listing all the active client requests running on all client
// managers on a particular sensing hub instance.
// - SNS_DIAG_SENSOR_MSGID_SNS_DIAG_DEBUG_EVENT is used to publish an event
// containing debug information

syntax = "proto2";
import "nanopb.proto";
import "sns_std_type.proto";
import "sns_client.proto";
import "sns_direct_channel.proto";

// @brief Stream requests and events.
enum sns_diag_sensor_msgid {
  option (nanopb_enumopt).long_names = false;

  SNS_DIAG_SENSOR_MSGID_SNS_DIAG_LOG_TRIGGER_REQ = 520;

  // @brief Request msg ID to query active client requests running on
  // client manager.
  SNS_DIAG_SENSOR_MSGID_SNS_DIAG_GET_CM_ACTIVE_CLIENT_REQ = 521;

  // @brief Request msg ID to query debug information.
  SNS_DIAG_SENSOR_MSGID_SNS_DIAG_DEBUG_REQ = 522;

  // @brief A single Event sent to client for the active client requests
  // running on  Client manager.
  SNS_DIAG_SENSOR_MSGID_SNS_DIAG_CM_ACTIVE_CLIENT_REQ_EVENT = 800;

  // @brief Event sent to client containing debug information.
  SNS_DIAG_SENSOR_MSGID_SNS_DIAG_DEBUG_EVENT = 801;
}

// @brief Log packets that can be triggered by the diag sensor.
enum sns_diag_triggered_log_type {
  option (nanopb_enumopt).long_names = false;

  // @brief Triggers generation not initialized.
  SNS_DIAG_TRIGGERED_LOG_TYPE_UNINITIALIZED = 0;

  // @brief Triggers generation of sns_diag_island_transition_log.
  // Only one log is generated per request. ( see sns_diag.proto,
  // sns_diag_island_log message for more details.)
  SNS_DIAG_TRIGGERED_LOG_TYPE_ISLAND_LOG = 1;

  // @brief Triggers generation of sns_diag_mem_utilization_log.
  // A single request will generate a log for each separate memory
  // pool in the system. ( see sns_diag.proto, sns_diag_mem_utilization_log
  // message for more details.)
  SNS_DIAG_TRIGGERED_LOG_TYPE_MEMORY_USAGE_LOG = 2;
}

// @brief Trigger generation of log packets. Depending upon
// the type of log packet that is being triggered,
// multiple log packets can be triggered for each
// request.
//
// If the log packet that is triggered has been disabled
// no log will be generated.
message sns_diag_log_trigger_req {

  // @brief User defined cookie.
  // Used by test scripts to identify logs triggered
  // by messages sent to the SSC.
  optional fixed64 cookie = 1;

  // @brief The type of log packets that the diag sensor must
  // generate.
  required sns_diag_triggered_log_type log_type = 2;
}

// @brief An Event generated by Diag sensor listing all the active
// client request running on Client Manager and Direct Channel Client
// Manager. It may be split into multiple Events.
message sns_diag_cm_active_client_req_event {

  message request_msg {

    // @brief Timestamp (in ticks) when request was received by Client manager
    // to activate sensor.
    required fixed64 timestamp = 1;

    // @brief Client request.
    required sns_client_request_msg request = 2;
  }

  repeated request_msg cm_request = 1;

  message direct_channel_request_msg {
    message direct_channel_create_msg {
      // @brief Timestamp when the create request was received by direct channel
      // client manager.
      optional fixed64 timestamp = 1;

      // @brief Create request
      optional sns_direct_channel_create_msg request = 2;
    }

    optional direct_channel_create_msg create_request = 1;

    message direct_channel_config_msg {
      // @brief Timestamp (in ticks) when the last configuration request was
      // received by direct channel client manager.
      optional fixed64 timestamp = 1;

      // @brief Configuration request
      optional sns_direct_channel_config_msg request = 2;
    }

    repeated direct_channel_config_msg config_request = 2;
  }

  // @brief Client may send multiple config requests on the same channel if
  // the direct channel type is DIRECT_CHANNEL_TYPE_STRUCTURED_MUX_CHANNEL.
  repeated direct_channel_request_msg direct_channel_cm_request = 2;

  // @brief partial_event is set to true if additional
  // sns_diag_cm_active_client_req_event messages will be sent to the client,
  // and set to false for the final message.
  optional bool partial_event = 3 [default = false];
}


// @brief Debug mask flags for filtering debug state information
// These masks can be combined using bitwise OR to request multiple debug states
// Note: These are bitmask values
enum sns_diag_debug_mask
{
  option (nanopb_enumopt).long_names = false;

  // @brief No debug information requested
  SNS_DIAG_INVALID_DEBUG_MASK = 0x0;

  // @brief Request power rail debug information
  SNS_DIAG_POWER_RAIL_DEBUG_MASK = 0x1;

  // @brief Request sleep debug information
  SNS_DIAG_SLEEP_DEBUG_MASK = 0x2;

  // @brief Request clock debug information
  SNS_DIAG_CLOCK_DEBUG_MASK = 0x4;

  // @brief Request latency debug information
  SNS_DIAG_LATENCY_DEBUG_MASK = 0x8;

  // @brief Request bandwidth debug information
  SNS_DIAG_BANDWIDTH_DEBUG_MASK = 0x10;

  // @brief Request island mode debug information
  SNS_DIAG_ISLAND_DEBUG_MASK = 0x20;
}

// @brief Request message to query debug information
message sns_diag_debug_req
{
  // @brief Bitmask filter to request for specific debug states.
  // If it is not specified, all the debug states will be reported.
  // sns_diag_debug_mask values can be combined using bitwise OR to request for
  // multiple debug states.
  // Examples:
  // 1. SNS_DIAG_POWER_RAIL_DEBUG_MASK to request for power rail debug
  //    information only.
  // 2. (SNS_DIAG_POWER_RAIL_DEBUG_MASK | SNS_DIAG_CLOCK_DEBUG_MASK)
  //    to request both power rail and clock debug information
  optional uint32 debug_mask_filter = 1;
}

// @brief Power rail vote
enum sns_diag_power_rail_vote
{
  option (nanopb_enumopt).long_names = false;

  // @brief Power rail vote is unknown
  SNS_DIAG_POWER_RAIL_VOTE_UNKNOWN = 0;

  // @brief Power rail vote is off
  SNS_DIAG_POWER_RAIL_VOTE_OFF = 1;

  // @brief Power rail vote is on in low power mode
  SNS_DIAG_POWER_RAIL_VOTE_ON_LPM = 2;

  // @brief Power rail vote is on in normal power mode
  SNS_DIAG_POWER_RAIL_VOTE_ON_NPM = 3;
}

// @brief Power rail info
// Contains information about all power rails and their votes
message sns_diag_power_rail_info
{
  // @brief Information about a single power rail
  message rail_info
  {
    // @brief Name of the power rail
    optional string name = 1;

    // @brief Current state of the power rail
    message vote_state
    {
      // @brief Current vote on the power rail
      optional sns_diag_power_rail_vote vote = 1;

      // @brief Timestamp (in ticks) when the rail vote was set
      optional fixed64 vote_ts = 2;
    }

    // @brief Current state of this power rail
    optional vote_state state = 2;

    // @brief Client information for power rail
    message client
    {
      // @brief Name of the client using this power rail
      optional string name = 1;
    }

    // @brief List of clients using this power rail
    repeated client clients = 3;
  }

  // @brief List of all power rails
  repeated rail_info rails = 1;
}


// @brief Island mode vote status
enum sns_diag_island_vote
{
  option (nanopb_enumopt).long_names = false;

  // @brief Island vote status is unknown or not initialized
  SNS_DIAG_ISLAND_VOTE_UNKNOWN = 0;

  // @brief Client is blocking island mode entry
  // Prevents the system from entering low-power island mode
  SNS_DIAG_ISLAND_VOTE_BLOCK = 1;

  // @brief Client is not blocking island mode entry
  // Allows the system to enter low-power island mode
  SNS_DIAG_ISLAND_VOTE_UNBLOCK = 2;
}

// @brief Island mode state information
// Contains information about all clients and their island mode votes
message sns_diag_island_info
{
  // @brief Information about a single island client
  message client_info
  {
    // @brief Name of the client
    optional string name = 1;

    // @brief Current state of the client's island mode vote
    message vote_state
    {
      // @brief Current island mode vote from this client
      optional sns_diag_island_vote vote = 1;

      // @brief Timestamp when the client vote was set (in ticks)
      optional fixed64 vote_ts = 2;
    }

    // @brief Current state of this client's island mode vote
    optional vote_state state = 2;

    // @brief Duration of the last island block period (in ticks)
    // Only valid if the client has previously blocked island mode.
    // Note: The current island block duration is not included if the client is
    // currently blocking island.
    optional fixed64 last_block_duration = 3;
  }

  // @brief List of all island clients
  repeated client_info clients = 1;
}

// @brief Clock domain identifiers
// Identifies different clock domains in the system that can be voted on
enum sns_diag_clock_id
{
  option (nanopb_enumopt).long_names = false;

  // @brief Clock ID is unknown or not initialized
  SNS_DIAG_CLOCK_ID_UNKNOWN = 0;

  // @brief Clock ID for processor running the sensing hub
  SNS_DIAG_CLOCK_ID_CPU = 1;

  // @brief SDC clock
  SNS_DIAG_CLOCK_ID_SDC = 2;

  // @brief CCD clock
  SNS_DIAG_CLOCK_ID_CCD = 3;

  // @brief PRAM clock
  SNS_DIAG_CLOCK_ID_PRAM = 4;

  // @brief PSC clock
  SNS_DIAG_CLOCK_ID_PSC = 5;
}

// @brief Clock info
// Contains information about all clients and their clock frequency votes
message sns_diag_clock_info
{
  // @brief Information about a single client's clock vote
  message client_info
  {
    // @brief Name of the client
    optional string name = 1;

    // @brief Clock domain being voted on
    optional sns_diag_clock_id clock_id = 2;

    // @brief Clock frequency vote in Hz
    optional uint64 clock_vote = 3;
  }

  // @brief List of all clients with clock votes
  repeated client_info clients = 1;
}

// @brief Latency vote status
enum sns_diag_latency_vote_status
{
  option (nanopb_enumopt).long_names = false;

  // @brief Latency vote status is unknown or not initialized
  SNS_DIAG_LATENCY_VOTE_STATUS_UNKNOWN = 0;

  // @brief Latency vote is active
  SNS_DIAG_LATENCY_VOTE_STATUS_ACTIVE = 1;

  // @brief Latency vote is inactive
  SNS_DIAG_LATENCY_VOTE_STATUS_INACTIVE = 2;
}

// @brief Latency info
// Contains information about all clients and their latency requirement votes
message sns_diag_latency_info
{
  // @brief Information about a single client's latency vote
  message client_info
  {
    // @brief Name of the client
    optional string name = 1;

    // @brief Maximum acceptable latency vote in microseconds
    optional uint64 latency_vote = 2;

    // @brief Current status of this client's latency vote
    optional sns_diag_latency_vote_status latency_vote_status = 3;

    // @brief Timestamp when this vote state was last updated (in ticks)
    optional fixed64 latency_vote_ts = 4;

    // @brief Last duration for which latency vote remained active (in ticks)
    // Note: The current active duration is not included if the client currently
    // has an active latency vote
    optional fixed64 last_active_duration = 5;
  }

  // @brief List of all clients with latency votes
  repeated client_info clients = 1;
}

// @brief Sleep processor identifiers
enum sns_diag_sleep_proc
{
  option (nanopb_enumopt).long_names = false;

  // @brief Sleep processor is unknown or not initialized
  SNS_DIAG_SLEEP_PROC_UNKNOWN = 0;

  // @brief Processor running the sensing hub
  SNS_DIAG_SLEEP_PROC_CPU = 1;

  // @brief SDC processor
  SNS_DIAG_SLEEP_PROC_SDC = 2;
}

// @brief Sleep info
// Contains information about processor and their wakeup rate requirements
message sns_diag_sleep_info
{
  // @brief Information about a single CPU's sleep configuration
  message proc_info
  {
    // @brief Processor identifier
    optional sns_diag_sleep_proc proc = 1;

    // @brief Wakeup rate requirements for different power modes
    message wakeup_rate_info
    {
      // @brief Wakeup rate in Low Power Mode (Hz)
      // Identifies how frequently the CPU needs to wake up in LPM
      optional uint32 lpm = 1;

      // @brief Wakeup rate in Normal Power Mode (Hz)
      // Identifies how frequently the CPU needs to wake up in NPM
      optional uint32 npm = 2;
    }

    // @brief Current wakeup rate configuration for this CPU
    optional wakeup_rate_info wakeup_rate = 2;
  }

  // @brief List of all processors with sleep configurations
  repeated proc_info procs = 1;
}

// @brief Bandwidth processor identifiers
// Identifies which processor is requesting bandwidth
enum sns_diag_bandwidth_proc
{
  option (nanopb_enumopt).long_names = false;

  // @brief Bandwidth processor is unknown or not initialized
  SNS_DIAG_BANDWIDTH_PROC_UNKNOWN = 0;

  // @brief Bandwidth processor running the sensing hub
  SNS_DIAG_BANDWIDTH_PROC_CPU = 1;

  // @brief Bandwidth processor is SDC
  SNS_DIAG_BANDWIDTH_PROC_SDC = 2;
}

// @brief Bandwidth memory types
// Identifies the memory type for bandwidth requests
enum sns_diag_bandwidth_memory
{
  option (nanopb_enumopt).long_names = false;

  // @brief Bandwidth memory is unknown or not initialized
  SNS_DIAG_BANDWIDTH_MEMORY_UNKNOWN = 0;

  // @brief Bandwidth memory is DDR
  SNS_DIAG_BANDWIDTH_MEMORY_DDR = 1;

  // @brief Bandwidth memory is SRAM
  SNS_DIAG_BANDWIDTH_MEMORY_SRAM = 2;

  // @brief Bandwidth memory is TCM
  SNS_DIAG_BANDWIDTH_MEMORY_TCM = 3;
}

// @brief Bandwidth info
// Contains information about all clients and their bandwidth votes
message sns_diag_bandwidth_info
{
  // @brief Information about a single client's bandwidth vote
  message client_info
  {
    // @brief Name of the client
    optional string name = 1;

    // @brief Processor making the bandwidth request
    optional sns_diag_bandwidth_proc proc = 2;

    // @brief Memory type for the bandwidth request
    optional sns_diag_bandwidth_memory memory = 3;

    // @brief Bandwidth vote in bytes per second
    optional uint64 bandwidth_vote = 4;
  }

  // @brief List of all clients with bandwidth votes
  repeated client_info clients = 1;
}

// @brief Debug information
message sns_diag_debug_info
{
  // @brief Contains one of the requested debug information types based on the
  // debug_mask_filter in sns_diag_debug_req
  oneof debug_info
  {
    // @brief Power rail info
    // Sent when SNS_DIAG_POWER_RAIL_DEBUG_MASK is set
    sns_diag_power_rail_info power_rail_info = 1;

    // @brief Clock info
    // Sent when SNS_DIAG_CLOCK_DEBUG_MASK is set
    sns_diag_clock_info clock_info = 2;

    // @brief Latency info
    // Sent when SNS_DIAG_LATENCY_DEBUG_MASK is set
    sns_diag_latency_info latency_info = 3;

    // @brief Sleep info
    // Sent when SNS_DIAG_SLEEP_DEBUG_MASK is set
    sns_diag_sleep_info sleep_info = 4;

    // @brief Bandwidth info
    // Sent when SNS_DIAG_BANDWIDTH_DEBUG_MASK is set
    sns_diag_bandwidth_info bandwidth_info = 5;

    // @brief Island mode info
    // Sent when SNS_DIAG_ISLAND_DEBUG_MASK is set
    sns_diag_island_info island_info = 6;
  }
}

// @brief Event message containing debug information
// Response to sns_diag_debug_req. Multiple events may be sent
// if the requested debug information is too large for a single message.
message sns_diag_debug_event
{
  // @brief Indicates if this is a partial event
  // When true, additional sns_diag_debug_event messages will be sent.
  // When false, this is the final (or only) sns_diag_debug_event message.
  optional bool partial_event = 1;

  // @brief List of debug information entries
  // Contains the requested debug information types based on the
  // debug_mask_filter in sns_diag_debug_req
  repeated sns_diag_debug_info debug_info = 2;
}

