README

   1 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   2 This is APC - graphical CPU load meter.
   3
   4 It is more suitable/accurate in situations where applications generate
   5 "short" periodic bursts of activity.
   6
   7 It works by timing the time spent in the kernels idle handler. CPU
   8 load time is taken to mean:
   9      time spent in idle handler
  10 1 -  --------------------------
  11         total time elapsed
  12
  13 Kernel can use variety of values for HZ (most frequent: 100 250 1000)
  14
  15 PAL/SECAM video frame grabbers do so with  25/50 FPS frequency, if the
  16 pulse leads to   some application deciding  to  burn CPU (putting  the
  17 frame on the screen, encoding it, etc) chances  are good that the load
  18 you will  see  in top(1)  (or anything  `/proc/stat' based) would  not
  19 represent reality  accurately. Ditto for plain  video clips playing at
  20 25 fps.
  21
  22 When   frequency of aforementioned    bursts  devides HZ value  evenly
  23 reading `/proc/stat'  or `/proc/uptime'  can  make an  impression that
  24 sometimes machine gets loaded for a brief period of time but then goes
  25 idle again (for a while) then the cycle repeats. This is not the case,
  26 the machine  is constantly loaded (well  according to ad-hoc measuring
  27 via background niced process and/or APC)
  28
  29 If this line of thinking is correct one can not notice any load at all
  30 while watching  NTSC  content  (30fps - does not  divide  100/250/1000
  31 evenly)
  32
  33 Furthermore `/proc/stat'  exports monotonically increasing  load times
  34 but _NOT_  real time[1], so  there's omni-present sub-jiffy error. Not
  35 to mention that jiffy resolution is somewhat low.
  36
  37 If you  depend  on  sorta-kinda   semi-correct  load  meter  in  those
  38 conditions APC might present a better choice.
  39
  40 The kernel  module   part of APC  measures  how  much time   is  spent
  41 executing idle kernel function   - this information is  represented by
  42 yellow color, values obtained via `/proc/stat' are represented by red.
  43
  44 You  can use `-help' command  line option to   get a brief overview of
  45 tunable parameters.
  46
  47 Tested on[2]:
  48
  49 Linux 2.4.30   - AMD Athlon(tm) Processor (1.4 Ghz)
  50 Linux 2.6.17.6 - AMD Athlon(tm)64 X2 Dual Core Processor  3800+
  51 Linux 2.6.18   - AMD Athlon(tm)64 3800+
  52 Linux 2.6.18.3 - PowerPC 7447A
  53
  54 It's possible  that RMClock[3]  does something similar(load  measuring
  55 wise) on Microsoft Windows.
  56
  57 [1] Unlike `/proc/uptime'. But this one is useless for SMP
  58 [2] SMP not tested on 2.4 kernels, nor QUIRK mode. SMP on PPC wasn't
  59     tested at all
  60 [3] http://cpu.rightmark.org/products/rmclock.shtml
  61
  62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  63 To build you will need:
  64
  65 OCaml  - http://caml.inria.fr/ocaml/
  66 LablGL - http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgl.html
  67          (and by extension some OpenGL implementation)
  68 GLUT   - http://www.opengl.org/resources/libraries/glut/
  69          http://freeglut.sourceforge.net/
  70 GCC    - http://gcc.gnu.org/
  71
  72 Plus all what is required to build a kernel module.
  73
  74 Process:
  75
  76 <untar and go to directory with sources>
  77 $ sh build.sh
  78 $ cd mod
  79 $ su -c 'insmod ./its.ko' - 2.6 Kernels
  80 $ su -c 'insmod ./its.o'  - 2.4 Kernels
  81
  82 Following applies only to Linux running on X86.
  83
  84 If the module fails to load consult dmesg(8). Most likely cause is the
  85 lack  of  exported `default_idle'    function  and no   specific power
  86 management idle function is specified. Few workarounds follow:
  87
  88 Variant 1
  89     Add `idle=halt' to the kernel command  line (method depends on the
  90     boot-loader) and reboot.
  91
  92 Variant 2 (DANGEROUS)
  93     ------------------------------------------------------------------
  94     Kernel 2.6
  95     $ func=$(awk '/default_idle$/ {print "0x" $1}' /proc/kallsyms)
  96     $ su -c "insmod ./itc.ko idle_func=$func"
  97
  98     ------------------------------------------------------------------
  99     Kernel 2.4
 100     $ func=$(awk '/default_idle$/ {print "0x" $1}' /proc/ksyms)
 101     $ su -c "insmod ./itc.o idle_func=$func"
 102
 103 ======================================================================
 104 $ cd ..
 105 $ major=$(awk '/ itc$/ {print $1}' /proc/devices)
 106 $ su -c "mknod -m 0444 itc c $major 0"
 107
 108 [make sure you are in X]
 109 $ ./apc