// @file sns_client.proto
//
// Defines the interface between external clients and the Sensors QMI Client
// Manager.  The Client Manager is the primary path for external clients
// to communicate with the SSC.
//
// Copyright (c) 2016-2018 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.
syntax = "proto2";
import "nanopb.proto";
import "sns_std_type.proto";
import "sns_std.proto";

// Message IDs
//
// Message IDs uniquely identify a particular message amongst all message
// supported by a Sensor, both requests and events; they need not be unique
// between different Sensors.  IDs are subdivided into several reserved pools.
// These reservations are made so that Framework components can appropriately
// optimize their processing.
//
// Reserved for Framework use only:
// 0-127   - Request Messages
// 128-255 - Non-recurrent events (configuration updates, one-time events, etc)
// 256-511 - Recurrent and/or periodic events (e.g. sensor samples)
//
// Sensor use:
// 512-767  - Request messages
// 768-1023 - Non-recurrent events
// 1024-1536 - Recurrent events
//
// Note that messages serving as request messages can also be sent as
// configuration events back to the client (with the same ID).  While batching
// data for a non-wakeup client, if the AP is in suspend and all batching space
// exhausted, the oldest recurrent events may be dropped.

// Framework-defined message IDs:
enum sns_client_msgid {
  option (nanopb_enumopt).long_names = false;

  // Disable request explicitly handled only on the client interface.
  SNS_CLIENT_MSGID_SNS_CLIENT_DISABLE_REQ = 10;

  // NOTE: 120-127 Are reserved
}

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

  // Send events whenever available (at sample rate or batch period)
  // - If a batch_period larger than system capacity is requested, all data
  //   will be sent upon capacity exhaustion.
  // - The flush_period will be effectively ignored, as unsent batched
  //   data will not accrue in the buffer.
  SNS_CLIENT_DELIVERY_WAKEUP = 0;
  // Send events only when client processor is awake; batch otherwise.  Once
  // the target processor exits suspend, any/all pending events will be sent.
  SNS_CLIENT_DELIVERY_NO_WAKEUP = 1;
}


// Request Message
message sns_client_request_msg {
  // SUID associated with this request; intended destination
  required sns_std_suid suid = 1;

  // See comment above
  required fixed32 msg_id = 2;

  // Whether to wakeup the client processor (if it is in suspend), when an
  // event is generated and ready to send.  The Qualcomm Client Manager will
  // enforce these criteria for all clients; this information is made available
  // to sensors for optimization purposes only.
  message suspend_config {
    // Processor on which the client resides; If a flush occurs for one client
    // on an external processor, all clients will receive a flush of data.
    required sns_std_client_processor client_proc_type = 1 [default = SNS_STD_CLIENT_PROCESSOR_APSS];

    // Whether to send events while the specified processor is in suspend.
    required sns_client_delivery  delivery_type = 2 [default = SNS_CLIENT_DELIVERY_WAKEUP];

    //The client expects that, when the message with an id specified in this list
    //is generated, the message should only be delivered to the client if data
    //is already being delivered to the processor mentioned above.
    repeated fixed32 nowakeup_msg_ids = 3;
  }
  required suspend_config susp_config = 3;

  // Base message payload; contents will be partially specified by Sensor developer
  required sns_std_request request = 4;
}

message sns_client_event_msg {
  // SUID associated with this Event; source of data
  required sns_std_suid suid = 1;

  // An event generated by a Sensor; used within sns_client_event_msg and SensorBatchMessage
  message sns_client_event {
    // See comment above
    required fixed32 msg_id = 1;

    // Timestamp associated with this event
    // For most events, this timestamp is specified by the Sensor.
    // For events generated by the Framework (such as configuration updates or
    // error events), this timestamp refers to the time at which the event was
    // created.
    required fixed64 timestamp = 2;

    // Dynamic length payload, containing the actual data/event
    // This payload will need to be decoded separately, using the Sensor-specific
    // header file
    required bytes payload = 3;
  }
  repeated sns_client_event events = 2;
}
