README

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