/*
 * Copyright (C) 2018 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";

import "protos/perfetto/common/builtin_clock.proto";

package perfetto.protos;

// A snapshot of clock readings to allow for trace alignment.
message ClockSnapshot {
  message Clock {
    // DEPRECATED. This enum has moved to ../common/builtin_clock.proto.
    enum BuiltinClocks {
      UNKNOWN = 0;
      REALTIME = 1;
      REALTIME_COARSE = 2;
      MONOTONIC = 3;
      MONOTONIC_COARSE = 4;
      MONOTONIC_RAW = 5;
      BOOTTIME = 6;
      BUILTIN_CLOCK_MAX_ID = 63;

      reserved 7, 8;
    }

    // Clock IDs have the following semantic:
    // [1, 63]:    Builtin types, see BuiltinClock from
    //             ../common/builtin_clock.proto.
    // [64, 127]:  User-defined clocks. These clocks are sequence-scoped. They
    //             are only valid within the same |trusted_packet_sequence_id|
    //             (i.e. only for TracePacket(s) emitted by the same TraceWriter
    //             that emitted the clock snapshot).
    // [128, MAX]: Reserved for future use. The idea is to allow global clock
    //             IDs and setting this ID to hash(full_clock_name) & ~127.
    optional uint32 clock_id = 1;

    // Absolute timestamp. Unit is ns unless specified otherwise by the
    // unit_multiplier_ns field below.
    optional uint64 timestamp = 2;

    // When true each TracePacket's timestamp should be interpreted as a delta
    // from the last TracePacket's timestamp (referencing this clock) emitted by
    // the same packet_sequence_id. Should only be used for user-defined
    // sequence-local clocks. The first packet timestamp after each
    // ClockSnapshot that contains this clock is relative to the |timestamp| in
    // the ClockSnapshot.
    optional bool is_incremental = 3;

    // Allows to specify a custom unit different than the default (ns) for this
    // clock domain.
    //
    // * A multiplier of 1000 means that a timestamp = 3 should be interpreted
    //   as 3000 ns = 3 us.
    // * All snapshots for the same clock within a trace need to use the same
    //   unit.
    // * `unit_multiplier_ns` is *not* supported for the `primary_trace_clock`.
    optional uint64 unit_multiplier_ns = 4;
  }
  repeated Clock clocks = 1;

  // The authoritative clock domain for the trace. When set, this definitively
  // overrides the trace time clock. If not set, the trace time clock remains
  // at its default (BUILTIN_CLOCK_TRACE_FILE), unless a format-specific
  // fallback applies (e.g. BOOTTIME for legacy proto traces without clock
  // snapshots). Trace processor will attempt to translate packet/event
  // timestamps from various data sources (and their chosen clock domains) to
  // this domain during import.
  optional BuiltinClock primary_trace_clock = 2;
}
