1 /* 2 * Copyright (C) 2011 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 __CLOCK_RECOVERY_H__ 18 #define __CLOCK_RECOVERY_H__ 19 20 #include <stdint.h> 21 #include <common_time/ICommonClock.h> 22 #include <utils/LinearTransform.h> 23 #include <utils/threads.h> 24 25 #ifdef TIME_SERVICE_DEBUG 26 #include "diag_thread.h" 27 #endif 28 29 #include "utils.h" 30 31 namespace android { 32 33 class CommonClock; 34 class LocalClock; 35 36 class ClockRecoveryLoop { 37 public: 38 ClockRecoveryLoop(LocalClock* local_clock, CommonClock* common_clock); 39 ~ClockRecoveryLoop(); 40 41 void reset(bool position, bool frequency); 42 bool pushDisciplineEvent(int64_t local_time, 43 int64_t nominal_common_time, 44 int64_t data_point_rtt); 45 int32_t getLastErrorEstimate(); 46 47 // Applies the next step in any ongoing slew change operation. Returns a 48 // timeout suitable for use with poll/select indicating the number of mSec 49 // until the next change should be applied. 50 int applyRateLimitedSlew(); 51 52 private: 53 54 // Tuned using the "Good Gain" method. 55 // See: 56 // http://techteach.no/publications/books/dynamics_and_control/tuning_pid_controller.pdf 57 58 // Controller period (1Hz for now). 59 static const float dT; 60 61 // Controller gain, positive and unitless. Larger values converge faster, 62 // but can cause instability. 63 static const float Kc; 64 65 // Integral reset time. Smaller values cause loop to track faster, but can 66 // also cause instability. 67 static const float Ti; 68 69 // Controller output filter time constant. Range (0-1). Smaller values make 70 // output smoother, but slow convergence. 71 static const float Tf; 72 73 // Low-pass filter for bias tracker. 74 static const float bias_Fc; // HZ 75 static const float bias_RC; // Computed in constructor. 76 static const float bias_Alpha; // Computed inconstructor. 77 78 // The maximum allowed error (as indicated by a pushDisciplineEvent) before 79 // we panic. 80 static const int64_t panic_thresh_; 81 82 // The maximum allowed error rtt time for packets to be used for control 83 // feedback, unless the packet is the best in recent memory. 84 static const int64_t control_thresh_; 85 86 typedef struct { 87 int64_t local_time; 88 int64_t observed_common_time; 89 int64_t nominal_common_time; 90 int64_t rtt; 91 bool point_used; 92 } DisciplineDataPoint; 93 94 static uint32_t findMinRTTNdx(DisciplineDataPoint* data, uint32_t count); 95 96 void reset_l(bool position, bool frequency); 97 void setTargetCorrection_l(int32_t tgt); 98 bool applySlew_l(); 99 100 // The local clock HW abstraction we use as the basis for common time. 101 LocalClock* local_clock_; 102 bool local_clock_can_slew_; 103 104 // The common clock we end up controlling along with the lock used to 105 // serialize operations. 106 CommonClock* common_clock_; 107 Mutex lock_; 108 109 // parameters maintained while running and reset during a reset 110 // of the frequency correction. 111 bool last_error_est_valid_; 112 int32_t last_error_est_usec_; 113 float last_delta_f_; 114 int32_t integrated_error_; 115 int32_t tgt_correction_; 116 int32_t cur_correction_; 117 LinearTransform time_to_cur_slew_; 118 int64_t slew_change_end_time_; 119 Timeout next_slew_change_timeout_; 120 121 // Contoller Output. 122 float CO; 123 124 // Bias tracking for trajectory estimation. 125 float CObias; 126 float lastCObias; 127 128 // Controller output bounds. The controller will not try to 129 // slew faster that +/-100ppm offset from center per interation. 130 static const float COmin; 131 static const float COmax; 132 133 // State kept for filtering the discipline data. 134 static const uint32_t kFilterSize = 16; 135 DisciplineDataPoint filter_data_[kFilterSize]; 136 uint32_t filter_wr_; 137 bool filter_full_; 138 139 static const uint32_t kStartupFilterSize = 4; 140 DisciplineDataPoint startup_filter_data_[kStartupFilterSize]; 141 uint32_t startup_filter_wr_; 142 143 // Minimum number of milliseconds over which we allow a full range change 144 // (from rail to rail) of the VCXO control signal. This is the rate 145 // limiting factor which keeps us from changing the clock rate so fast that 146 // we get in trouble with certain HDMI sinks. 147 static const uint32_t kMinFullRangeSlewChange_mSec; 148 149 // How much time (in msec) to wait 150 static const int kSlewChangeStepPeriod_mSec; 151 152 #ifdef TIME_SERVICE_DEBUG 153 sp<DiagThread> diag_thread_; 154 #endif 155 }; 156 157 } // namespace android 158 159 #endif // __CLOCK_RECOVERY_H__ 160