README

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