1 /* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_AUDIO_TIMESTAMP_H 18 #define ANDROID_AUDIO_TIMESTAMP_H 19 20 #include <string> 21 #include <sstream> 22 #include <time.h> 23 24 namespace android { 25 26 class AudioTimestamp { 27 public: AudioTimestamp()28 AudioTimestamp() : mPosition(0) { 29 mTime.tv_sec = 0; 30 mTime.tv_nsec = 0; 31 } 32 // FIXME change type to match android.media.AudioTrack 33 uint32_t mPosition; // a frame position in AudioTrack::getPosition() units 34 struct timespec mTime; // corresponding CLOCK_MONOTONIC when frame is expected to present 35 }; 36 37 struct alignas(8) /* bug 29096183, bug 29108507 */ ExtendedTimestamp { 38 enum Location { 39 LOCATION_INVALID = -1, 40 // Locations in the audio playback / record pipeline. 41 LOCATION_CLIENT, // timestamp of last read frame from client-server track buffer. 42 LOCATION_SERVER, // timestamp of newest frame from client-server track buffer. 43 LOCATION_KERNEL, // timestamp of newest frame in the kernel (alsa) buffer. 44 45 // Historical data: info when the kernel timestamp was OK (prior to the newest frame). 46 // This may be useful when the newest frame kernel timestamp is unavailable. 47 // Available for playback timestamps. 48 LOCATION_SERVER_LASTKERNELOK, // timestamp of server the prior time kernel timestamp OK. 49 LOCATION_KERNEL_LASTKERNELOK, // timestamp of kernel the prior time kernel timestamp OK. 50 LOCATION_MAX // for sizing arrays only 51 }; 52 53 // This needs to be kept in sync with android.media.AudioTimestamp 54 enum Timebase { 55 TIMEBASE_MONOTONIC, // Clock monotonic offset (generally 0) 56 TIMEBASE_BOOTTIME, 57 TIMEBASE_MAX, 58 }; 59 ExtendedTimestampExtendedTimestamp60 ExtendedTimestamp() { 61 clear(); 62 } 63 64 // mPosition is expressed in frame units. 65 // It is generally nonnegative, though we keep this signed for 66 // to potentially express algorithmic latency at the start of the stream 67 // and to prevent unintentional unsigned integer underflow. 68 int64_t mPosition[LOCATION_MAX]; 69 70 // mTimeNs is in nanoseconds for the default timebase, monotonic. 71 // If this value is -1, then both time and position are invalid. 72 // If this value is 0, then the time is not valid but the position is valid. 73 int64_t mTimeNs[LOCATION_MAX]; 74 75 // mTimebaseOffset is the offset in ns from monotonic when the 76 // timestamp was taken. This may vary due to suspend time 77 // or NTP adjustment. 78 int64_t mTimebaseOffset[TIMEBASE_MAX]; 79 80 // Playback only: 81 // mFlushed is number of flushed frames before entering the server mix; 82 // hence not included in mPosition. This is used for adjusting server positions 83 // information for frames "dropped". 84 // FIXME: This variable should be eliminated, with the offset added on the server side 85 // before sending to client, but differences in legacy position offset handling 86 // and new extended timestamps require this to be maintained as a separate quantity. 87 int64_t mFlushed; 88 89 // Call to reset the timestamp to the original (invalid) state clearExtendedTimestamp90 void clear() { 91 memset(mPosition, 0, sizeof(mPosition)); // actually not necessary if time is -1 92 for (int i = 0; i < LOCATION_MAX; ++i) { 93 mTimeNs[i] = -1; 94 } 95 memset(mTimebaseOffset, 0, sizeof(mTimebaseOffset)); 96 mFlushed = 0; 97 } 98 99 // Returns the best timestamp as judged from the closest-to-hw stage in the 100 // pipeline with a valid timestamp. If the optional location parameter is non-null, 101 // it will be filled with the location where the time was obtained. 102 status_t getBestTimestamp( 103 int64_t *position, int64_t *time, int timebase, Location *location = nullptr) const { 104 if (position == nullptr || time == nullptr 105 || timebase < 0 || timebase >= TIMEBASE_MAX) { 106 return BAD_VALUE; 107 } 108 // look for the closest-to-hw stage in the pipeline with a valid timestamp. 109 // We omit LOCATION_CLIENT as we prefer at least LOCATION_SERVER based accuracy 110 // when getting the best timestamp. 111 for (int i = LOCATION_KERNEL; i >= LOCATION_SERVER; --i) { 112 if (mTimeNs[i] > 0) { 113 *position = mPosition[i]; 114 *time = mTimeNs[i] + mTimebaseOffset[timebase]; 115 if (location != nullptr) { 116 *location = (Location)i; 117 } 118 return OK; 119 } 120 } 121 return INVALID_OPERATION; 122 } 123 124 status_t getBestTimestamp(AudioTimestamp *timestamp, Location *location = nullptr) const { 125 if (timestamp == nullptr) { 126 return BAD_VALUE; 127 } 128 int64_t position, time; 129 if (getBestTimestamp(&position, &time, TIMEBASE_MONOTONIC, location) == OK) { 130 timestamp->mPosition = position; 131 timestamp->mTime.tv_sec = time / 1000000000; 132 timestamp->mTime.tv_nsec = time - timestamp->mTime.tv_sec * 1000000000LL; 133 return OK; 134 } 135 return INVALID_OPERATION; 136 } 137 138 // convert fields to a printable string toStringExtendedTimestamp139 std::string toString() { 140 std::stringstream ss; 141 142 ss << "BOOTTIME offset " << mTimebaseOffset[TIMEBASE_BOOTTIME] << "\n"; 143 for (int i = 0; i < LOCATION_MAX; ++i) { 144 ss << "ExtendedTimestamp[" << i << "] position: " 145 << mPosition[i] << " time: " << mTimeNs[i] << "\n"; 146 } 147 return ss.str(); 148 } 149 // TODO: 150 // Consider adding buffer status: 151 // size, available, algorithmic latency 152 }; 153 154 } // namespace 155 156 #endif // ANDROID_AUDIO_TIMESTAMP_H 157