// @file sns_timer.proto
//
// Defines standard message types for the Timer Sensor
//
// Copyright (c) 2017 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.
syntax = "proto2";
import "nanopb.proto";

enum sns_timer_sensor_timeout
{
  option (nanopb_enumopt).long_names = false;

  SNS_TIMER_SENSOR_TIMEOUT_MIN_TIMEOUT_NANOSEC = 100000;
}

enum sns_timer_msgid {
  option (nanopb_enumopt).long_names = false;

  // Timer config message.
  //
  //Corresponds to the message sns_timer_sensor_config.
  // This message is used to start, reconfigure or
  // stop the timer sensor
  SNS_TIMER_MSGID_SNS_TIMER_SENSOR_CONFIG = 512;

  // Timer event message.
  //
  // Corresponds to the message sns_timer_sensor_event.
  // This event is generated when a timer's timeout
  // occurs.
  SNS_TIMER_MSGID_SNS_TIMER_SENSOR_EVENT  = 1025;

  // Timer registration message
  //
  // This message is used to acknowledge that a timer was successfully
  // registered. This event contains the sns_timer_reg_event with the
  // options selected by the timer sensor. The event will be re-sent each time
  // the timer sensor automatically adjusts the period of a periodic timer.
  SNS_TIMER_MSGID_SNS_TIMER_SENSOR_REG_EVENT = 1026;
}

// Priority of timer events
enum sns_timer_priority {
  option (nanopb_enumopt).long_names = false;
  // Priority LOWEST is used for low priority timers
  SNS_TIMER_PRIORITY_LOWEST  = 0;
  // Priority OTHER is used for general timer events, and should be used
  // by default
  SNS_TIMER_PRIORITY_OTHER   = 10;
  // Priority POLLING is used for polling physical sensors
  SNS_TIMER_PRIORITY_POLLING = 50;
  // Priority S4S is used for S4S schedules
  SNS_TIMER_PRIORITY_S4S     = 100;
}

// Timer configuration message.
// The minimum time resolution supported by the timer is
// min_timeout_nanosec

message sns_timer_sensor_config
{

  // The time of starting the timer in ticks. This is typically current time.
  required uint64 start_time = 1;

  // The timeout period starting from start_time, in ticks.
  required uint64 timeout_period = 2;

  // If this timer is periodic. If true, the timer will be rearmed to
  // timeout_period when the timer fires. If false, the timer will be disarmed
  // after firing once. The memory associated with this timer will not be
  // released until this connection is terminated.
  required bool is_periodic = 3;

  // The start_config allows the timer sensor to modify the start_time. This may
  // allow the timer sensor to synchronize with other nearby timers to save power
  // if the exact value of start_time is flexible.
  // If this message is not present, default values are 0.
  message start_config_message {
    // The start_time may be adjusted to start early by this many ticks.
    required uint32 early_start_delta = 1;
    // The start_time may be adjusted to start late by this many ticks.
    required uint32 late_start_delta = 2;
  }
  optional start_config_message start_config = 4;

  // The timeout_config allows the timer sensor to modify the timeout_period.
  // This may allow the timer sensor to synchronize with other timers to save
  // power if the exact perodicity is flexible.
  // If this message is not present, default values are 0.
  message timeout_config_message {
    // The initial timeout_period may be adjusted smaller by this many ticks.
    required uint32 low_timeout_delta = 1;
    // The initial timeout_period may be adjusted larger by this many ticks.
    required uint32 high_timeout_delta = 2;

    // jitter_ticks only applies if "is_periodic" is true. After the first
    // TIMER_SENSOR_EVENT, the timeout_period will only be adjusted by this many
    // ticks in each period. The accumulated adjustments will stay within the
    // low/high bounds defined in this message.
    optional uint32 jitter_ticks = 3;
  }
  optional timeout_config_message timeout_config = 5;

  // Set this to true to cause the timer sensor to send a TIMER_SENSOR_REG_EVENT
  // and include this timer as part of the timers to be synchronized, but the
  // timer will not actually be started, and no TIMER_SENSOR_EVENTs will
  // be generated.
  // This is useful to know how to synchronize to other timers on the system
  // without actually causing timer events to occur.
  optional bool is_dry_run = 6 [default = false];

  // If multiple timers expire at the same time, timer events with higher
  // priority will be sent first.
  // default: other
  optional sns_timer_priority priority = 7 [default = SNS_TIMER_PRIORITY_OTHER];
}

// Timer Sensor event
// This event is generated each time the timer fires. The time at which the timer
// fires can differ from the requested timeout by up to min_timeout_nanosec.
// The client is responsible for checking the requested_timeout_time and the
// timeout_time fields and determine if additional delays must be added.
message sns_timer_sensor_event
{
  // The timeout period generated from the timer_sensor_config message in ticks.
  required uint64 requested_timeout_time = 1;

  // The time at which the timer fired, in ticks.
  required uint64 timeout_time = 2;
}

// Timer registration message
//
// This message is used to acknowledge that a timer was successfully
// registered. This event contains options selected by the timer sensor based
// on the config event.
// The event will be re-sent each time the timer sensor automatically adjusts
// the period of a periodic timer.
message sns_timer_sensor_reg_event
{
  required uint64             start_time     = 1;
  required uint64             timeout_period = 2;
  required bool               is_periodic    = 3;
  required bool               is_dry_run     = 4;
  required sns_timer_priority priority       = 5;
}
