include/linux/timecounter.h

   1 /*
   2  * linux/include/linux/timecounter.h
   3  *
   4  * based on code that migrated away from
   5  * linux/include/linux/clocksource.h
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  */
  17 #ifndef _LINUX_TIMECOUNTER_H
  18 #define _LINUX_TIMECOUNTER_H
  19
  20 #include <linux/types.h>
  21
  22 /* simplify initialization of mask field */
  23 #define CYCLECOUNTER_MASK(bits) (u64)((bits) < 64 ? ((1ULL<<(bits))-1) : -1)
  24
  25 /**
  26  * struct cyclecounter - hardware abstraction for a free running counter
  27  *      Provides completely state-free accessors to the underlying hardware.
  28  *      Depending on which hardware it reads, the cycle counter may wrap
  29  *      around quickly. Locking rules (if necessary) have to be defined
  30  *      by the implementor and user of specific instances of this API.
  31  *
  32  * @read:               returns the current cycle value
  33  * @mask:               bitmask for two's complement
  34  *                      subtraction of non 64 bit counters,
  35  *                      see CYCLECOUNTER_MASK() helper macro
  36  * @mult:               cycle to nanosecond multiplier
  37  * @shift:              cycle to nanosecond divisor (power of two)
  38  */
  39 struct cyclecounter {
  40         u64 (*read)(const struct cyclecounter *cc);
  41         u64 mask;
  42         u32 mult;
  43         u32 shift;
  44 };
  45
  46 /**
  47  * struct timecounter - layer above a %struct cyclecounter which counts nanoseconds
  48  *      Contains the state needed by timecounter_read() to detect
  49  *      cycle counter wrap around. Initialize with
  50  *      timecounter_init(). Also used to convert cycle counts into the
  51  *      corresponding nanosecond counts with timecounter_cyc2time(). Users
  52  *      of this code are responsible for initializing the underlying
  53  *      cycle counter hardware, locking issues and reading the time
  54  *      more often than the cycle counter wraps around. The nanosecond
  55  *      counter will only wrap around after ~585 years.
  56  *
  57  * @cc:                 the cycle counter used by this instance
  58  * @cycle_last:         most recent cycle counter value seen by
  59  *                      timecounter_read()
  60  * @nsec:               continuously increasing count
  61  * @mask:               bit mask for maintaining the 'frac' field
  62  * @frac:               accumulated fractional nanoseconds
  63  */
  64 struct timecounter {
  65         const struct cyclecounter *cc;
  66         u64 cycle_last;
  67         u64 nsec;
  68         u64 mask;
  69         u64 frac;
  70 };
  71
  72 /**
  73  * cyclecounter_cyc2ns - converts cycle counter cycles to nanoseconds
  74  * @cc:         Pointer to cycle counter.
  75  * @cycles:     Cycles
  76  * @mask:       bit mask for maintaining the 'frac' field
  77  * @frac:       pointer to storage for the fractional nanoseconds.
  78  */
  79 static inline u64 cyclecounter_cyc2ns(const struct cyclecounter *cc,
  80                                       u64 cycles, u64 mask, u64 *frac)
  81 {
  82         u64 ns = (u64) cycles;
  83
  84         ns = (ns * cc->mult) + *frac;
  85         *frac = ns & mask;
  86         return ns >> cc->shift;
  87 }
  88
  89 /**
  90  * timecounter_adjtime - Shifts the time of the clock.
  91  * @delta:      Desired change in nanoseconds.
  92  */
  93 static inline void timecounter_adjtime(struct timecounter *tc, s64 delta)
  94 {
  95         tc->nsec += delta;
  96 }
  97
  98 /**
  99  * timecounter_init - initialize a time counter
 100  * @tc:                 Pointer to time counter which is to be initialized/reset
 101  * @cc:                 A cycle counter, ready to be used.
 102  * @start_tstamp:       Arbitrary initial time stamp.
 103  *
 104  * After this call the current cycle register (roughly) corresponds to
 105  * the initial time stamp. Every call to timecounter_read() increments
 106  * the time stamp counter by the number of elapsed nanoseconds.
 107  */
 108 extern void timecounter_init(struct timecounter *tc,
 109                              const struct cyclecounter *cc,
 110                              u64 start_tstamp);
 111
 112 /**
 113  * timecounter_read - return nanoseconds elapsed since timecounter_init()
 114  *                    plus the initial time stamp
 115  * @tc:          Pointer to time counter.
 116  *
 117  * In other words, keeps track of time since the same epoch as
 118  * the function which generated the initial time stamp.
 119  */
 120 extern u64 timecounter_read(struct timecounter *tc);
 121
 122 /**
 123  * timecounter_cyc2time - convert a cycle counter to same
 124  *                        time base as values returned by
 125  *                        timecounter_read()
 126  * @tc:         Pointer to time counter.
 127  * @cycle_tstamp:       a value returned by tc->cc->read()
 128  *
 129  * Cycle counts that are converted correctly as long as they
 130  * fall into the interval [-1/2 max cycle count, +1/2 max cycle count],
 131  * with "max cycle count" == cs->mask+1.
 132  *
 133  * This allows conversion of cycle counter values which were generated
 134  * in the past.
 135  */
 136 extern u64 timecounter_cyc2time(struct timecounter *tc,
 137                                 u64 cycle_tstamp);
 138
 139 #endif