api.htm

内核中关于nano计时的功能

            <dl>
                <dt><tt>STA_UNSYNC</tt> or <tt>STA_CLOCKERR</tt> is set.
                <dd>Either the clock is not synchronized to a reliable server or a failure has occurred in the external clock or clock driver, if provisioned.
                <dt><tt>STA_PPSSIGNAL</tt> is reset and either <tt>STA_PPSFREQ</tt> or <tt>STA_PPSTIME</tt> is set).
                <dd>The synchronization daemon has requested use of the PPS signal, but the signal has not been detected during the last two minutes.
                <dt><tt>STA_PPSTIME</tt> and <tt>STA_PPSJITTER</tt> are both set.
                <dd>The synchronization daemon has requested PPS time discipline, but the jitter has exceeded the limit.
                <dt><tt>STA_PPSFREQ</tt> is set and either <tt>STA_PPSWANDER</tt> or <tt>STA_PPSERROR</tt> is set.
                <dd>The synchronization daemon has requested PPS frequency discipline, but either the frequency wander has exceeded the limit or a frequency measurement has failed due to a glitch.
            </dl>
        </dl>
        <p>There are two additional return codes which can be produced by the kernel. These include the following system-dependent error numbers defined in the <tt>/usr/include/errno.h</tt> header file. Note that the values of these error numbers may collide with the above return codes in some systems.</p>
        <dl>
            <dt><tt>EPERM</tt>
            <dd>Not superuser - attempt to change kernel variables without root privilege.
            <dt><tt>EINVAL</tt>
            <dd>Invalid argument - attempt to set both <tt>MOD_MICRO</tt> and <tt>MOD_NANO</tt> or <tt>MOD_CLKB</tt> and <tt>MOD_CLKA</tt> simultaneously
        </dl>
        <h4 id="#mode">Mode Control Bits</h4>
        <p>The following mode bits specify which kernel values are to be changed in the <tt>ntp_adjtime()</tt> system call, as well as the format used for time values and whether an external clock is selected.</p>
        <dl>
            <dt><tt>MOD_OFFSET</tt><br>
                <tt>MOD_FREQUENCY</tt><br>
                <tt>MOD_MAXERROR</tt><br>
                <tt>MOD_ESTERROR</tt><br>
                <tt>MOD_STATUS</tt><br>
                <tt>MOD_TIMECONST</tt><br>
                <tt>MOD_PPSMAX</tt>
            <dd>These bits control which field of the timex structure are used to update the corresponding kernel variable. The bits may be set in any combination. See the description below for which bits control which variable.
            <dt><tt>MOD_NANO</tt><br>
                <tt>MOD_MICRO</tt>
            <dd>These two bits control the scale used in the API interface (but not the actual operations used by the clock discipline algorithm). Only one of the two bits should be set. <tt>MOD_NANO</tt> selects seconds and nanoseconds (<tt>timespec</tt> format), while <tt>MOD_MICRO</tt> selects seconds and microseconds (timeval format). This applies to both the time value returned by <tt>ntp_gettime()</tt> and the offset used by <tt>ntp_adjtime()</tt>. Note that not all kernels can support nanosecond format. The recommended behavior is to select one or the other format and inspect the <tt>STA_NANO</tt> bit in the status word to determine the actual kernel mode. The default when the kernel is first booted is seconds and microseconds for legacy compatibility.
            <dt><tt>MOD_CLKA</tt><br>
                <tt>MOD_CLKB</tt>
            <dd>These two bits control the operation of an external clock, if present in the architecture. Only one of the two bits should be set. <tt>MOD_CLKB</tt> sets the <tt>STA_CLK</tt> bit in the status word, while the <tt>MOD_CLKA</tt> resets it. The behavior in response to the <tt>STA_CLK</tt> bit is beyond the scope of the current implementation.
        </dl>
        <h4 id="#adjtime">The <tt>ntp_adjtime()</tt> System Call</h4>
        <p>The <tt>ntp_adjtime()</tt> system call is used to set and read kernel variables used by kernel. It operates using the <tt>timex</tt> structure described in the <tt>timex.h</tt> header file. This structure is used both to change the values of certain kernel variables and to return the current values. Root privilege is required to change the values. Following are the variables that can be read and written. The return codes are described in the <a href="#leap">Return Codes and the Leap-Second State Machine</a> section on this page.</p>
        <dl>
            <dt><tt>offset</tt>
            <dd>If the <tt>MOD_OFFSET</tt> bit is set in the mode word, this variable updates the kernel time offset in nanoseconds, if the <tt>STA_NANO</tt> bit is set in the status word, or in microseconds if not.
            <dt><tt>freq</tt>
            <dd>If the <tt>MOD_FREQUENCY</tt> bit is set in the mode word, this variable updates the kernel frequency offset. This is ordinarily done only when the clock discipline algorithm is first started, since the frequency is automatically determined by the algorithm after that. The format of this variable is in PPM with a 16-bit fraction field.
            <dt><tt>maxerror</tt>
            <dd>If the <tt>MOD_MAXERROR</tt> bit is set in the mode word, this variable updates the kernel maximum error in microseconds. The error is automatically updated by the clock discipline algorithm after that and until the next update. The value is not used for any purpose other than to provide a conduit from the synchronization daemon to the user applications.
            <dt><tt>esterror</tt>
            <dd>If the <tt>MOD_ESTERROR</tt> bit is set in the mode word, this variable updates the kernel estimated error in microseconds. The value is not used for any purpose other than to provide a conduit from the synchronization daemon to the user applications.
            <dt><tt>status</tt>
            <dd>If the <tt>MOD_STATUS</tt> bit is set in the mode word, this variable updates the read/write bits in the status word.
            <dt><tt>shift</tt>
            <dd>This variable is actually two variables, one write-only and the other read-only. When written, the value represents the maximum calibration cycle length expressed in seconds as a power of two. When read, the value represents the current calibration cycle length expressed in seconds as a power of two.
        </dl>
        <p>The following variables are read-only.</p>
        <dl>
            <dt><tt>precision</tt>
            <dd>Precision of the system clock, in nanoseconds if the <tt>STA_NANO</tt> bit is set in the status word, or in microseconds if not.
            <dt><tt>tolerance</tt>
            <dd>Frequency tolerance of the clock discipline algorithm, in the same units as the <tt>freq</tt> variable described above. More precisely, the maximum clock oscillator frequency error that can be corrected by the clock discipline algorithm.
        </dl>
        <p>The following variables are read-only and present only if the PPS clock discipline code has been compiled and configured in the kernel. They are included in the <tt>timex</tt> structure definition to insure portability.</p>
        <dl>
            <dt><tt>ppsfreq</tt>
            <dd>Frequency calculated by the PPS loop, in the same units as the <tt>freq</tt> variable described above. This calculation is independent of all other means to adjust the system clock frequency. If enabled by the API and the PPS signal is within nominals, the clock frequency should be identical to this value.
            <dt><tt>jitter</tt>
            <dd>Average phase jitter, in nanoseconds if the <tt>STA_NANO</tt> bit is set in the status word, or in microseconds if not.
            <dt><tt>stabil</tt>
            <dd>Average wander, in the same units as the <tt>freq</tt> variable described above.
            <dt><tt>jitcnt</tt>
            <dd>Count of excess phase jitter occurrences. See the <a href="descrip.htm">Principles of Operation</a> page for further details.
            <dt><tt>calcnt</tt>
            <dd>Count of calibration intervals. See the <a href="descrip.htm">Principles of Operation</a> page for further details.
            <dt><tt>errcnt</tt>
            <dd>Count of calibration error occurrences. See the <a href="descrip.htm">Principles of Operation</a> page for further details.
            <dt><tt>errcnt</tt>
            <dd>Count of excess frequency wander occurrences. See the <a href="descrip.htm">Principles of Operation</a> page for further details.
        </dl>
        <h4 id="#gettime">The <tt>ntp_gettime()</tt> System Call</h4>
        <p>The <tt>ntp_gettime()</tt> system call is used to read the current system time and related error variables. It uses the <tt>ntptimeval</tt> structure described in the <tt>timex.h</tt> header file. This structure includes the following variables. The return codes are described in the <a href="#leap">Return Codes and the Leap-Second State Machine</a> section on this page.</p>
        <dl>
            <dt><tt>time</tt>
            <dd>Current system clock time, in <tt>timespec</tt> format if <tt>STA_NANO</tt> is set in the status word; in <tt>timeval</tt> format if not.
            <dt><tt>maxerror</tt>
            <dd>Maximum credible absolute error of the system clock, in microseconds. The value is initialized by the <tt>ntp_adjtime()</tt> system call and incremented by the kernel after that. The value is not used for any purpose other than to provide a conduit from the synchronization daemon to the user applications.
            <dt><tt>esterror</tt>
            <dd>Estimated RMS error of the system clock, in microseconds. The value is initialized by the <tt>ntp_adjtime()</tt> system call, but not used for any purpose other than to provide a conduit from the synchronization daemon to the user applications.
            <dt><tt>tai</tt>
            <dd>Current offset of TAI relative to UTC, as provided by the Autokey protocol and the NIST leapseconds file.
        </dl>
        <hr>
        <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
    </body>

</html>