1// Copyright 2022 The Pigweed Authors 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); you may not 4// use this file except in compliance with the License. You may obtain a copy of 5// the License at 6// 7// https://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12// License for the specific language governing permissions and limitations under 13// the License. 14 15syntax = "proto3"; 16 17package pw.chrono; 18 19option java_outer_classname = "Chrono"; 20 21message EpochType { 22 enum Enum { 23 UNKNOWN = 0; 24 25 TIME_SINCE_BOOT = 1; 26 27 // Time since 00:00:00 UTC, Thursday, 1 January 1970, including leap 28 // seconds. 29 UTC_WALL_CLOCK = 2; 30 31 // Time since 00:00:00, 6 January 1980 UTC. Leap seconds are not inserted 32 // into GPS. Thus, every time a leap second is inserted into UTC, UTC 33 // falls another second behind GPS. 34 GPS_WALL_CLOCK = 3; 35 36 // Time since 00:00:00, 1 January 1958, and is offset 10 seconds ahead of 37 // UTC at that date (i.e., its epoch, 1958-01-01 00:00:00 TAI, is 38 // 1957-12-31 23:59:50 UTC). Leap seconds are not inserted into TAI. Thus, 39 // every time a leap second is inserted into UTC, UTC falls another second 40 // behind TAI. 41 TAI_WALL_CLOCK = 4; 42 }; 43} 44 45// A representation of a clock's parameters. 46// 47// There are two major components to representing a steady, monotonic clock: 48// 49// 1. A representation of the clock's period. 50// 2. A representation of the clock's epoch. 51// 52// To support a wide range of clock configurations, ClockParameters represents 53// a clock's period as fractions of a second. Concretely: 54// 55// Clock period (seconds) = 56// tick_period_seconds_numerator / tick_period_seconds_denominator 57// 58// So a simple 1KHz clock can be represented as: 59// 60// tick_period_seconds_numerator = 1 61// tick_period_seconds_denominator = 1000 62// Clock period = 1 / 1000 = 0.001 seconds 63// Clock frequency = 1 / 0.001 = 1,000 Hz 64// 65// Failing to specify one or both of the period members of a ClockParameters 66// message leaves the configuration specification incomplete and invalid. 67// 68// While clock period alone is enough to represent a duration if given a number 69// of ticks, an epoch is required to make a clock represent a time point. 70// EpochType optionally provides this information. Specifying an EpochType 71// defines what a tick count of `0` represents. Some epoch types (e.g. UTC, GPS, 72// TAI) allow the clock to resolve to real-world time points. If the EpochType 73// is relative to boot or unknown, however, the clock is only sufficiently 74// specified for relative time measurement without additional external 75// information. 76message ClockParameters { 77 int32 tick_period_seconds_numerator = 1; // Required 78 int32 tick_period_seconds_denominator = 2; // Required 79 optional EpochType.Enum epoch_type = 3; 80} 81 82// A point in time relative to a clock's epoch. 83message TimePoint { 84 // The duration that has elapsed (number of clock ticks) since the epoch, 85 // where the tick period and epoch are specified by the clock parameters. 86 // 87 // The meaning of `timestamp` is unspecified without an associated 88 // ClockParameters. 89 int64 timestamp = 1; // Required 90 ClockParameters clock_parameters = 2; // Required 91} 92 93// The time of a snapshot capture. Supports multiple timestamps to 94// cover multiple time bases or clocks (e.g. time since boot, time 95// from epoch, etc). 96// 97// This is an overlay proto for Snapshot, see more details here: 98// https://pigweed.dev/pw_snapshot/proto_format.html#module-specific-data 99message SnapshotTimestamps { 100 repeated TimePoint timestamps = 22; 101} 102