v0.97c
[apc.git] / README
blobe5a6d012fea075eda77b0c996a7840f25735f7bb
1 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2 WARNING
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:
7                      NO GUARANTEES WHATSOEVER
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.
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'.
22 2.4 series of kernels were never tested on SMP as such the module will
23 refuse to build for them.
25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26 This is APC - graphical CPU load meter.
28 It is more suitable/accurate in situations where applications generate
29 "short" periodic bursts of activity.
31 It works by measuring the time spent in  the kernels idle handler. CPU
32 load time is taken to mean:
34      time spent in idle handler
35 1 -  --------------------------
36         total time elapsed
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.
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.
48 Apart    from   being inaccurate,  `/proc/stat'  exports monotonically
49 increasing load times but _NOT_  real time[1], so there's omni-present
50 sub-jiffy error. Not to mention that jiffy resolution is somewhat low.
52 If you depend on sorta-kinda semi-correct load meter in situation when
53 `/proc/stat'  is disconnected with reality  APC might present a better
54 choice.
56 The kernel  module part  of APC   tries to insert  itself  as  a power
57 management idle  handler and when  invoked measure  how  much time  is
58 spent executing previous/default one - this information is represented
59 by yellow color, values  obtained via `/proc/stat' are represented  by
60 red.
62 You  can use `-help' command  line option to   get a brief overview of
63 tunable parameters.
65 Tested on[2]:
67 Linux 2.4.30   - AMD Athlon(tm) Processor (1.4 Ghz)
68 Linux 2.6.17.6
69 Linux 2.6.19.2 - AMD Athlon(tm)64 X2 Dual Core Processor  3800+
70 Linux 2.6.18   - AMD Athlon(tm)64 3800+
71 Linux 2.6.18.3 - PowerPC 7447A
72 Linux 2.6.19   - [some Core 2 Duo]
74 It's possible  that RMClock[3]  does something similar(load  measuring
75 wise) on Microsoft Windows.
77 [1] Unlike `/proc/uptime'. But this one is useless for SMP
78 [2] SMP not tested on 2.4 kernels, nor QUIRK mode. SMP on PPC wasn't
79     tested at all
80 [3] http://cpu.rightmark.org/products/rmclock.shtml
82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83 To build you will need:
85 OCaml  - http://caml.inria.fr/ocaml/
86 LablGL - http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgl.html
87          (and by extension some OpenGL implementation)
88 GLUT   - http://www.opengl.org/resources/libraries/glut/
89          http://freeglut.sourceforge.net/
90 GCC    - http://gcc.gnu.org/
92 Plus all what is required to build a kernel module.
94 Process:
96 <untar and go to directory with sources>
97 $ sh build.sh
99 # if following fails on X86 read bellow
100 $ su -c 'insmod mod/its.ko' - 2.6 Kernels
101 $ su -c 'insmod mod/its.o'  - 2.4 Kernels
103 $ major=$(awk '/ itc$/ {print $1}' /proc/devices)
104 $ su -c "mknod -m 0444 itc c $major 0"
106 [make sure you are in X]
107 $ ./apc
109 ``````````````````````````````````````````````````````````````````````
110 Following applies only to Linux running on X86.
112 If the module fails to load consult dmesg(8). Most likely cause is the
113 lack  of  exported `default_idle'    function  and no   specific power
114 management idle function is specified. Few workarounds follow:
116 Variant 1
117     Add `idle=halt' to the kernel command  line (method depends on the
118     boot-loader) and reboot.
120 Variant 2 (DANGEROUS)
121     ------------------------------------------------------------------
122     Kernel 2.6
123     $ func=$(awk '/default_idle$/ {print "0x" $1}' /proc/kallsyms)
124     $ su -c "/sbin/insmod ./itc.ko idle_func=$func"
126     ------------------------------------------------------------------
127     Kernel 2.4
128     $ func=$(awk '/default_idle$/ {print "0x" $1}' /proc/ksyms)
129     $ su -c "/sbin/insmod ./itc.o idle_func=$func"
131 ======================================================================