Home | History | Annotate | Download | only in common_time 
      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