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
   7                        NO GUARANTEES WHATSOEVER
   8
   9 Furthermore  removing the  previous    versions  of the  module   (via
  10 rmmod(8))      caused  one  particular      kernel   version to  panic
  11 (2.6.8-2-686-SMP  form Debian), to  the best  of  my current knowledge
  12 panics are only possible on SMP machines (and with maxcpus > 1).  Pair
  13 of safety nets were added and this  particular kernel no longer panics
  14 upon module removal, but, again, three words in caps above apply.
  15
  16 The module expects certain things not to happen at particular point in
  17 execution, otherwise the information kernel  module exports can not be
  18 trusted.   Those `things' did  happen on aforementioned Debian kernel,
  19 so if you need to run APC there you might want to uncomment first line
  20 of `mod/itc-mod.c'.
  21
  22 2.4 series of kernels were never tested on SMP as such the module will
  23 refuse to build for them.
  24
  25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  26                This is APC - graphical CPU load meter.
  27
  28 It is more suitable/accurate in situations where applications generate
  29 "short" periodic bursts of activity.
  30
  31 It works by measuring the time spent in  the kernels idle handler. CPU
  32 load time is taken to mean:
  33
  34      time spent in idle handler
  35 1 -  --------------------------
  36         total time elapsed
  37
  38 Con Kolivas  in  his post on   LKML (http://lkml.org/lkml/2007/2/12/7)
  39 described  the way   Linux  gathers information   that it exports   to
  40 `/proc/stat' (at least for "boring"  architectures), this method is by
  41 no means accurate and can "lie" in either direction.
  42
  43 You can witness this  by running the `hog'  example and, if  stars are
  44 aligned  correctly, you will notice  that something is wrong with what
  45 `/proc/stat' claims. Since most of the CPU monitoring applications use
  46 `/proc/stat' they will produce incorrect results too.
  47
  48 Note that  dyntick  kernels  will most   likely produce  different but
  49 still incorrect accounting.
  50 (For more information: http://lkml.org/lkml/2007/6/14/301 and bellow)
  51
  52 Kernel (starting with version 2.6.21) comes with a document describing
  53 the  way accounting is currently  done and problems with this approach
  54 (Documentation/cpu-load.txt)
  55
  56 Following thread describes a take on addressing the issue properly:
  57 http://marc.info/?t=117480935100001&r=1&w=2
  58
  59 Apart    from   being inaccurate,  `/proc/stat'  exports monotonically
  60 increasing load times but _NOT_  real time[1], so there's omni-present
  61 sub-jiffy error. Not to mention that jiffy resolution is somewhat low.
  62
  63 If you are  not running RT kernel  and  need sorta-kinda, semi-correct
  64 load meter in situation when `/proc/stat' is disconnected with reality
  65 APC might present a better choice.
  66
  67 The kernel  module part  of APC   tries to insert  itself  as  a power
  68 management idle  handler and when  invoked measure  how  much time  is
  69 spent executing previous/default one - this information is represented
  70 by yellow color, values  obtained via `/proc/stat' are represented  by
  71 red.
  72
  73 You  can use `-help' command  line option to   get a brief overview of
  74 tunable parameters.
  75
  76 Tested on[2]:
  77
  78 Linux 2.4.30   - AMD Athlon(tm) Processor (1.4 Ghz)
  79 Linux 2.6.17.6
  80 Linux 2.6.19.2 - AMD Athlon(tm)64 X2 Dual Core Processor  3800+
  81 Linux 2.6.18   - AMD Athlon(tm)64 3800+
  82 Linux 2.6.18.3 - PowerPC 7447A
  83 Linux 2.6.20.1 - PowerPC 7447A
  84 Linux 2.6.19   - [some Core 2 Duo]
  85
  86 It's possible  that RMClock[3]  does something similar(load  measuring
  87 wise) on Microsoft Windows.
  88
  89 [1] Unlike `/proc/uptime'. But this one is useless for SMP
  90 [2] SMP not tested on 2.4 kernels, nor QUIRK mode. SMP on PPC wasn't
  91     tested either
  92 [3] http://cpu.rightmark.org/products/rmclock.shtml
  93
  94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  95 To build idlestat (boring console application) you will need:
  96
  97 GCC    - http://gcc.gnu.org/
  98
  99 Plus all what is required to build a kernel module.
 100
 101 Process:
 102
 103 $ gcc -o idlestat idlestat.c
 104 $ cd mod && make
 105
 106 Idlestat (as well as APC) requires kernel module to be loaded in order
 107 for it to operate. Module loading is described below.
 108
 109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 110 To build APC (graphical application with bells etc) you will need:
 111
 112 OCaml  - http://caml.inria.fr/ocaml/
 113 LablGL - http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgl.html
 114          (and by extension some OpenGL implementation)
 115 GLUT   - http://www.opengl.org/resources/libraries/glut/
 116          http://freeglut.sourceforge.net/
 117 GCC    - http://gcc.gnu.org/
 118
 119 Plus all what is required to build a kernel module.
 120
 121 Process:
 122
 123 <untar and go to directory with sources>
 124 $ sh build.linux
 125
 126 # if following step fails(on X86) read next section before trying to
 127 # execute mknod
 128 $ su -c 'insmod mod/itc.ko' - 2.6 Kernels
 129 $ su -c 'insmod mod/itc.o'  - 2.4 Kernels
 130
 131 $ su -c "chmod +r /dev/itc"
 132
 133 [make sure you are in X]
 134 $ ./apc
 135
 136 ``````````````````````````````````````````````````````````````````````
 137 Following applies only to Linux running on X86.
 138
 139 If the module fails to load consult dmesg(8). Most likely cause is the
 140 lack of exported `default_idle'  function. Few workarounds follow.
 141
 142 Workarounds
 143
 144     Variant 1
 145         Add `idle=halt' to the  kernel command line (method depends on
 146         the boot-loader) and reboot.
 147
 148     Variant 2 (DANGEROUS)
 149         --------------------------------------------------------------
 150         Kernel 2.6
 151         $ func=$(awk '/default_idle$/ {print "0x" $1}' /proc/kallsyms)
 152         $ su -c "/sbin/insmod mod/itc.ko idle_func=$func"
 153
 154         --------------------------------------------------------------
 155         Kernel 2.4
 156         $ func=$(awk '/default_idle$/ {print "0x" $1}' /proc/ksyms)
 157         $ su -c "/sbin/insmod mod/itc.o idle_func=$func"
 158
 159 ======================================================================