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 19import "pw_tokenizer_proto/options.proto"; 20 21option java_outer_classname = "Chrono"; 22 23message EpochType { 24 enum Enum { 25 UNKNOWN = 0; 26 27 TIME_SINCE_BOOT = 1; 28 29 // Time since 00:00:00 UTC, Thursday, 1 January 1970, including leap 30 // seconds. 31 UTC_WALL_CLOCK = 2; 32 33 // Time since 00:00:00, 6 January 1980 UTC. Leap seconds are not inserted 34 // into GPS. Thus, every time a leap second is inserted into UTC, UTC 35 // falls another second behind GPS. 36 GPS_WALL_CLOCK = 3; 37 38 // Time since 00:00:00, 1 January 1958, and is offset 10 seconds ahead of 39 // UTC at that date (i.e., its epoch, 1958-01-01 00:00:00 TAI, is 40 // 1957-12-31 23:59:50 UTC). Leap seconds are not inserted into TAI. Thus, 41 // every time a leap second is inserted into UTC, UTC falls another second 42 // behind TAI. 43 TAI_WALL_CLOCK = 4; 44 }; 45} 46 47// A representation of a clock's parameters. 48// 49// There are two major components to representing a steady, monotonic clock: 50// 51// 1. A representation of the clock's period. 52// 2. A representation of the clock's epoch. 53// 54// To support a wide range of clock configurations, ClockParameters represents 55// a clock's period as fractions of a second. Concretely: 56// 57// Clock period (seconds) = 58// tick_period_seconds_numerator / tick_period_seconds_denominator 59// 60// So a simple 1KHz clock can be represented as: 61// 62// tick_period_seconds_numerator = 1 63// tick_period_seconds_denominator = 1000 64// Clock period = 1 / 1000 = 0.001 seconds 65// Clock frequency = 1 / 0.001 = 1,000 Hz 66// 67// Failing to specify one or both of the period members of a ClockParameters 68// message leaves the configuration specification incomplete and invalid. 69// 70// While clock period alone is enough to represent a duration if given a number 71// of ticks, an epoch is required to make a clock represent a time point. 72// EpochType optionally provides this information. Specifying an EpochType 73// defines what a tick count of `0` represents. Some epoch types (e.g. UTC, GPS, 74// TAI) allow the clock to resolve to real-world time points. If the EpochType 75// is relative to boot or unknown, however, the clock is only sufficiently 76// specified for relative time measurement without additional external 77// information. 78message ClockParameters { 79 int32 tick_period_seconds_numerator = 1; // Required 80 int32 tick_period_seconds_denominator = 2; // Required 81 optional EpochType.Enum epoch_type = 3; 82 optional bytes name = 4 [(tokenizer.format) = TOKENIZATION_OPTIONAL]; 83} 84 85// A point in time relative to a clock's epoch. 86message TimePoint { 87 // The duration that has elapsed (number of clock ticks) since the epoch, 88 // where the tick period and epoch are specified by the clock parameters. 89 // 90 // The meaning of `timestamp` is unspecified without an associated 91 // ClockParameters. 92 int64 timestamp = 1; // Required 93 ClockParameters clock_parameters = 2; // Required 94} 95 96// The time of a snapshot capture. Supports multiple timestamps to 97// cover multiple time bases or clocks (e.g. time since boot, time 98// from epoch, etc). 99// 100// This is an overlay proto for Snapshot, see more details here: 101// https://pigweed.dev/pw_snapshot/proto_format.html#module-specific-data 102message SnapshotTimestamps { 103 repeated TimePoint timestamps = 22; 104} 105