2 * Copyright (C) 2011 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __CLOCK_RECOVERY_H__
18 #define __CLOCK_RECOVERY_H__
21 #include <common_time/ICommonClock.h>
22 #include <utils/LinearTransform.h>
23 #include <utils/threads.h>
25 #ifdef TIME_SERVICE_DEBUG
26 #include "diag_thread.h"
36 class ClockRecoveryLoop {
38 ClockRecoveryLoop(LocalClock* local_clock, CommonClock* common_clock);
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();
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();
54 // Tuned using the "Good Gain" method.
56 // http://techteach.no/publications/books/dynamics_and_control/tuning_pid_controller.pdf
58 // Controller period (1Hz for now).
59 static const float dT;
61 // Controller gain, positive and unitless. Larger values converge faster,
62 // but can cause instability.
63 static const float Kc;
65 // Integral reset time. Smaller values cause loop to track faster, but can
66 // also cause instability.
67 static const float Ti;
69 // Controller output filter time constant. Range (0-1). Smaller values make
70 // output smoother, but slow convergence.
71 static const float Tf;
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.
78 // The maximum allowed error (as indicated by a pushDisciplineEvent) before
80 static const int64_t panic_thresh_;
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_;
88 int64_t observed_common_time;
89 int64_t nominal_common_time;
92 } DisciplineDataPoint;
94 static uint32_t findMinRTTNdx(DisciplineDataPoint* data, uint32_t count);
96 void reset_l(bool position, bool frequency);
97 void setTargetCorrection_l(int32_t tgt);
100 // The local clock HW abstraction we use as the basis for common time.
101 LocalClock* local_clock_;
102 bool local_clock_can_slew_;
104 // The common clock we end up controlling along with the lock used to
105 // serialize operations.
106 CommonClock* common_clock_;
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_;
114 int32_t tgt_correction_;
115 int32_t cur_correction_;
116 LinearTransform time_to_cur_slew_;
117 int64_t slew_change_end_time_;
118 Timeout next_slew_change_timeout_;
123 // Bias tracking for trajectory estimation.
127 // Controller output bounds. The controller will not try to
128 // slew faster that +/-100ppm offset from center per interation.
129 static const float COmin;
130 static const float COmax;
132 // State kept for filtering the discipline data.
133 static const uint32_t kFilterSize = 16;
134 DisciplineDataPoint filter_data_[kFilterSize];
138 static const uint32_t kStartupFilterSize = 4;
139 DisciplineDataPoint startup_filter_data_[kStartupFilterSize];
140 uint32_t startup_filter_wr_;
142 // Minimum number of milliseconds over which we allow a full range change
143 // (from rail to rail) of the VCXO control signal. This is the rate
144 // limiting factor which keeps us from changing the clock rate so fast that
145 // we get in trouble with certain HDMI sinks.
146 static const uint32_t kMinFullRangeSlewChange_mSec;
148 // How much time (in msec) to wait
149 static const int kSlewChangeStepPeriod_mSec;
151 #ifdef TIME_SERVICE_DEBUG
152 sp<DiagThread> diag_thread_;
156 } // namespace android
158 #endif // __CLOCK_RECOVERY_H__