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 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_;
119 
120     // Contoller Output.
121     float CO;
122 
123     // Bias tracking for trajectory estimation.
124     float CObias;
125     float lastCObias;
126 
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;
131 
132     // State kept for filtering the discipline data.
133     static const uint32_t kFilterSize = 16;
134     DisciplineDataPoint filter_data_[kFilterSize];
135     uint32_t filter_wr_;
136     bool filter_full_;
137 
138     static const uint32_t kStartupFilterSize = 4;
139     DisciplineDataPoint startup_filter_data_[kStartupFilterSize];
140     uint32_t startup_filter_wr_;
141 
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;
147 
148     // How much time (in msec) to wait
149     static const int kSlewChangeStepPeriod_mSec;
150 
151 #ifdef TIME_SERVICE_DEBUG
152     sp<DiagThread> diag_thread_;
153 #endif
154 };
155 
156 }  // namespace android
157 
158 #endif  // __CLOCK_RECOVERY_H__
159