1  [[cha:latency-test]]
  2  
  3  = Latency Test
  4  
  5  This test is the first test that should be performed on a PC 
  6  to see if it is able to drive a CNC machine.
  7  
  8  Latency is how long it takes the PC to stop what it is doing and 
  9  respond to an external request. For LinuxCNC the request is 
 10  BASE_THREAD that makes the periodic 'heartbeat' that serves as a 
 11  timing reference for the step pulses. The lower the latency, the 
 12  faster you can run the heartbeat, and the faster and smoother the 
 13  step pulses will be.
 14  
 15  Latency is far more important than CPU speed. 
 16  A lowly Pentium II that responds to interrupts within 10 microseconds 
 17  each and every time can give better results 
 18  than the latest and fastest P4 Hyperthreading beast.
 19  
 20  The CPU isn't the only factor in determining latency. 
 21  Motherboards, video cards, USB ports, and 
 22  a number of other things can hurt the latency. 
 23  The best way to find out what you are dealing with is 
 24  to run the RTAI latency test. 
 25  
 26  Generating step pulses in software 
 27  has one very big advantage - it's free. 
 28  Just about every PC has a parallel port that is 
 29  capable of outputting step pulses that are generated by the software. 
 30  However, software step pulses 
 31  also have some disadvantages:
 32  
 33   - limited maximum step rate 
 34   - jitter in the generated pulses
 35   - loads the CPU
 36  
 37  The best way to find out how well your PC will lrun LinuxCNC 
 38  is to run the HAL latency test. 
 39  To run the test, open a terminal window 
 40  (In Ubuntu, from Applications → Accessories → Terminal) 
 41  and run the following command: 
 42  
 43  ----
 44  latency-test
 45  ----
 46  
 47  You should see something like this:
 48  
 49  .HAL Latency Test
 50  
 51  image::../config/images/latency-test_en.png[align="center", alt="HAL Latency Test"]
 52  
 53  While the test is running, you should 'abuse' the computer. 
 54  Move windows around on the screen. Surf the web. Copy some large files 
 55  around on the disk. Play some music. 
 56  Run an OpenGL program such as glxgears. 
 57  The idea is to put the PC through its paces while 
 58  the latency test checks to see what the worst case numbers are. 
 59  
 60  [NOTE]
 61  Do not run LinuxCNC or Stepconf while the latency test is running.
 62  
 63  The important numbers are the 'max jitter'. 
 64  In the example above, that is 9075 nanoseconds, or 9.075 microseconds. 
 65  Record this number, and enter it in Stepconf when it is requested.
 66  
 67  In the example above, latency-test only ran for a few seconds. 
 68  You should run the test for at least several minutes; sometimes 
 69  the worst case latency doesn't happen very often, or only happens 
 70  when you do some particular action. For instance, one Intel 
 71  motherboard worked pretty well most of the time, but every 64 
 72  seconds it had a very bad 300 us latency. Fortunately that was 
 73  fixable, see http://wiki.linuxcnc.org/cgi-bin/wiki.pl?FixingSMIIssues
 74  
 75  So, what do the results mean? If your Max Jitter number is less 
 76  than about 15-20 microseconds (15000-20000 nanoseconds), the 
 77  computer should give very nice results with software stepping. If 
 78  the max latency is more like 30-50 microseconds, you can still 
 79  get good results, but your maximum step rate might be a little 
 80  disappointing, especially if you use microstepping or have very 
 81  fine pitch leadscrews. If the numbers are 100 us or more (100,000 
 82  nanoseconds), then the PC is not a good candidate for software 
 83  stepping. Numbers over 1 millisecond (1,000,000 nanoseconds) mean 
 84  the PC is not a good candidate for LinuxCNC, regardless of whether you 
 85  use software stepping or not.
 86  
 87  Note that if you get high numbers, there may be ways to improve 
 88  them. Another PC had very bad latency (several milliseconds) when 
 89  using the onboard video. But a $5 used video card solved the 
 90  problem.
 91  
 92  [NOTE]
 93  LinuxCNC does not require bleeding edge hardware.
 94  
 95  For more information on stepper tuning see the 
 96  <<cha:Stepper-Tuning,Stepper Tuning>> Chapter.
 97  
 98  Additional command line tools are availalbe for examining latency
 99  when LinuxCNC is not running.
100  
101  latency-plot makes a strip chart recording for a base and a servo
102  thread.  It may be useful to see spikes in latency when other
103  applications are started or used.  Usage:
104  ----
105  latency-plot --help
106  
107  Usage:
108        latency-plot --help | -?      (this)
109        latency-plot --hal [Options]
110  
111  Options:
112        --base nS  (base  thread interval, default:   25000)
113        --servo nS (servo thread interval, default: 1000000)
114        --time mS  (report interval, default: 1000)
115        --relative (relative clock time (default))
116        --actual   (actual clock time)
117  ----
118  image::../config/images/latency-plot.png[alt="latency-plot makes a strip chart recording for a base and a servo thread"]
119  
120  
121  latency-histogram displays a histogram of latency (jitter) for
122  a base and servo thread.
123  ----
124  Usage:
125     latency-histogram --help | -?
126  or
127     latency-histogram [Options]
128  
129  Options:
130    --base      nS   (base  thread interval, default:   25000, min:  5000)
131    --servo     nS   (servo thread interval, default: 1000000, min: 25000)
132    --bbinsize  nS   (base  bin size,  default: 100
133    --sbinsize  nS   (servo bin size, default: 100
134    --bbins     n    (base  bins, default: 200
135    --sbins     n    (servo bins, default: 200
136    --logscale  0|1  (y axis log scale, default: 1)
137    --text      note (additional note, default: "" )
138    --show           (show count of undisplayed bins)
139    --nobase         (servo thread only)
140    --verbose        (progress and debug)
141    --nox            (no gui, display elapsed,min,max,sdev for each thread)
142  
143  Notes:
144    Linuxcnc and Hal should not be running, stop with halrun -U.
145    Large number of bins and/or small binsizes will slow updates.
146    For single thread, specify --nobase (and options for servo thread).
147    Measured latencies outside of the +/- bin range are reported
148    with special end bars.  Use --show to show count for
149    the off-chart [pos|neg] bin
150  ----
151  image::../config/images/latency-histogram.png[alt="latency-histogram displays a histogram of latency (jitter) for a base and servo thread"]
152  
153  // vim: set syntax=asciidoc:
154