latency-histogram: include min,max,stddev

Also:
  When a bin had only one count, it was not
  showing when using y axis logscale -- so alter
  bin value from 1 to 1.1 to appear as a pip
  above the yaxis 1E0 line.

  Rearrange documenting lines for better fit with --nobase

Suggested by Peter Wallace
Thanks to jepler for rtapi_math64 with rtapi_div_u64

Signed-off-by: Dewey Garrett <dgarrett@panix.com>

Author: dngarrett

docs/src/config/images/latency-histogram.png

@@ -187,7 +187,7 @@ proc config {} {
     exit 1
   }
 
-  set ::LH(title) "$::argv0 $::LH(note,txt)"
+  set ::LH(title) "$::argv0"
   wm title . $::LH(title)
 
   foreach thd $::LH(threads) {
@@ -226,14 +226,10 @@ proc other_info {} {
   }
   set linuxcncversion [exec linuxcnc_var LINUXCNCVERSION]
   return "\
-$::LH(date) \
-[exec hostname] \
 $::tcl_platform(machine) \
 $::tcl_platform(osVersion) \
 $linuxcncversion \
 $display \
-$::tcl_platform(user) \
-$::LH(note,txt) \
 "
 } ;# other_info
 
@@ -340,10 +336,18 @@ proc load_packages {} {
 proc make_gui { {w .} } {
   set f [frame ${w}fa]
   pack $f -side top -fill x -expand 1
-  pack [label $f.l -anchor w -text $::LH(info)] -fill x -expand 1
+  set hname [exec hostname]
+  set user $::tcl_platform(user)
+  pack [label $f.l -anchor w \
+       -text "$::LH(date) $hname $user $::LH(note,txt)"
+       ] -fill x -expand 1
 
   set f [frame ${w}fb]
   pack $f -side top -fill x -expand 1
+  pack [label $f.l -anchor w -text $::LH(info)] -fill x -expand 1
+
+  set f [frame ${w}fc]
+  pack $f -side top -fill x -expand 1
   pack [label $f.l -anchor w -text $::LH(processor)] -fill x -expand 1
 
   set fmain [frame ${w}fmain]
@@ -369,8 +373,29 @@ proc make_gui { {w .} } {
     xaxis $thd
     $::LH(w,$thd) axis configure y -logscale $::LH(y,logscale)
 
+    set f [frame $f1.extra12]
+    pack $f -side top -anchor w -fill x -expand 1
+
+    pack [label $f.min -text "min (us)"] \
+         -side left -anchor e
+    set e [entry $f.emin -textvariable ::LH($thd,latency_min,us) \
+         -state readonly -justify right -width 9]
+    pack $e -side left -anchor e
+
+    pack [label $f.sdev -text "      sdev (us):"] \
+         -side left
+    set e [entry $f.esdev  -textvariable ::LH($thd,latency_sdev,us) \
+         -state readonly -justify right -width 9]
+    pack $e -side left -anchor e
+
+    set e [entry $f.emax  -textvariable ::LH($thd,latency_max,us) \
+         -state readonly -justify right -width 9]
+    pack $e -side right -anchor e
+    pack [label $f.max -text "max(us)"] \
+         -side right -anchor e
+
     if $::LH(opt,show) {
-      set f [frame $f1.extra]
+      set f [frame $f1.extra2]
       pack $f -side top -anchor w -fill x -expand 1
       set e [entry $f.emin -textvariable ::LH($thd,n,more) \
            -state readonly -justify right -width 9]
@@ -511,6 +536,9 @@ proc reset_data {} {
     set ::LH($thd,nextra) 0
     set ::LH($thd,p,more) 0
     set ::LH($thd,n,more) 0
+    set ::LH($thd,latency_min,us)  ""
+    set ::LH($thd,latency_max,us)  ""
+    set ::LH($thd,latency_sdev,us) ""
   }
   after 100
   foreach thd $::LH(threads) {
@@ -647,10 +675,9 @@ proc update_chart {thd} {
     set pbin [hal getp $::LH($thd,name).pbinvalue]
     set nbin [hal getp $::LH($thd,name).nbinvalue]
 
-    #verify index in range
-    #if { ($pbin < 0) ||  ($nbin < 0) } {
-    #  puts stderr "Unexpected: thd=$thd index=$bin pbin=$pbin, nbin=$nbin"
-    #}
+    # 1.1 value makes single unit bins show as pips when using log y scale:
+    if {$pbin == 1} {set pbin 1.1}
+    if {$nbin == 1} {set nbin 1.1}
 
     lappend pxd [expr $bin * $::LH($thd,binsize,us)]
     lappend pyd $pbin
@@ -664,6 +691,19 @@ proc update_chart {thd} {
     }
   } ;# for bin
 
+  set ::LH($thd,latency_min,us) [format %.1f \
+               [expr 1e-3 * [hal getp $::LH($thd,name).latency-min]]]
+  set ::LH($thd,latency_max,us) [format %.1f \
+               [expr 1e-3 * [hal getp $::LH($thd,name).latency-max]]]
+
+  set variance [hal getp $::LH($thd,name).variance]
+  if [catch {
+    set ::LH($thd,latency_sdev,us) [format %.1f \
+               [expr 1e-3 * sqrt($variance)]]
+    } msg] {
+    puts msg=$msg
+  }
+
   set ::LH($thd,pextra) [hal getp $::LH($thd,name).pextra]
   set ::LH($thd,p,more) [expr $pmore + $::LH($thd,pextra)]
 

scripts/latency-histogram

@@ -13,11 +13,13 @@ Usage:
   Iterate:
     Set index pin to a bin number: 0 <= index <= maxbinnumber.
     Read check pin and verify that check pin == index pin.
-    Read pbinvalue,nbinvalue,pextra,nextra pins.
-         (pbinvalue is count for bin = +index)
-         (nbinvalue is count for bin = -index)
-         (pextra    is count for all bins > maxbinnumber)
-         (nextra    is count for all bins < maxbinnumber)
+    Read output pins:
+         pbinvalue is count for bin = +index
+         nbinvalue is count for bin = -index
+         pextra    is count for all bins > maxbinnumber
+         nextra    is count for all bins < maxbinnumber
+         latency-min is max negative latency
+         latency-max is max positive latency
 
    If index is out of range ( index < 0 or index > maxbinnumber)
    then pbinvalue = nbinvalue = -1.
@@ -34,10 +36,13 @@ pin in  s32 nsbinsize;
 
 pin out s32 check;
 pin out s32 latency;
+pin out s32 latency_max;
+pin out s32 latency_min;
 pin out s32 pbinvalue;
 pin out s32 nbinvalue;
 pin out s32 pextra;
 pin out s32 nextra;
+pin out s32 variance;
 
 // user may interrogate available bins to determine this compiled-in limit
 pin out s32 availablebins = 1000; // MAXBINNUMBER
@@ -50,6 +55,10 @@ variable int    pbins[1001]; // MAXBINNUMBER+1
 variable int    nbins[1001]; // MAXBINNUMBER+1
 variable int    binmax = 0;
 
+variable rtapi_u32 nsamples;
+variable rtapi_u64 sum;
+variable rtapi_u64 sq_sum;
+
 license "GPL";
 ;;
 
@@ -73,13 +82,20 @@ if (   first
   ) {
   first = 0;
   latency = 0;
+  latency_min = 0x7FFFFFFF;
+  latency_max = 0x80000000;
   pextra = 0; nextra = 0;
   for (i = 0; i <= binmax; i++) {
     pbins[i] = 0; nbins[i] = 0;
   }
+  nsamples = 0;
+  sum = 0;
+  sq_sum = 0;
 } else {
   latency = lat32;
   i = lat32/nsbinsize;
+  if (lat32 > latency_max) latency_max = lat32;
+  if (lat32 < latency_min) latency_min = lat32;
   if (i >= 0) {
      if (i > binmax) {
        pextra++;
@@ -94,6 +110,17 @@ if (   first
        nbins[i]++;
      }
   }
+  nsamples++;
+  sum    += lat32;
+  sq_sum += lat32 * lat32;
+  if (nsamples > 1) {
+    // note: divison required is: u64/u32
+    rtapi_u64 dividend;
+    rtapi_u64 divisor;
+    dividend = sq_sum - rtapi_div_u64(sum * sum,nsamples);
+    divisor  = nsamples -1;
+    variance = rtapi_div_u64(dividend,divisor);
+  }
 }
 
 check = index; // user should verify check==index for reading values