tools/power/cpupower/README

   1 The cpupower package consists of the following elements:
   2
   3 requirements
   4 ------------
   5
   6 On x86 pciutils is needed at runtime (-lpci).
   7 For compilation pciutils-devel (pci/pci.h) and a gcc version
   8 providing cpuid.h is needed.
   9 For both it's not explicitly checked for (yet).
  10
  11
  12 libcpupower
  13 ----------
  14
  15 "libcpupower" is a library which offers a unified access method for userspace
  16 tools and programs to the cpufreq core and drivers in the Linux kernel. This
  17 allows for code reduction in userspace tools, a clean implementation of
  18 the interaction to the cpufreq core, and support for both the sysfs and proc
  19 interfaces [depending on configuration, see below].
  20
  21
  22 compilation and installation
  23 ----------------------------
  24
  25 There are 2 output directories - one for the build output and another for
  26 the installation of the build results, that is the utility, library,
  27 man pages, etc...
  28
  29 default directory
  30 -----------------
  31
  32 In the case of default directory, build and install process requires no
  33 additional parameters:
  34
  35 build
  36 -----
  37
  38 $ make
  39
  40 The output directory for the 'make' command is the current directory and
  41 its subdirs in the kernel tree:
  42 tools/power/cpupower
  43
  44 install
  45 -------
  46
  47 $ sudo make install
  48
  49 'make install' command puts targets to default system dirs:
  50
  51 -----------------------------------------------------------------------
  52 | Installing file        |               System dir                   |
  53 -----------------------------------------------------------------------
  54 | libcpupower            | /usr/lib                                   |
  55 -----------------------------------------------------------------------
  56 | cpupower               | /usr/bin                                   |
  57 -----------------------------------------------------------------------
  58 | cpufreq-bench_plot.sh  | /usr/bin                                   |
  59 -----------------------------------------------------------------------
  60 | man pages              | /usr/man                                   |
  61 -----------------------------------------------------------------------
  62
  63 To put it in other words it makes build results available system-wide,
  64 enabling any user to simply start using it without any additional steps
  65
  66 custom directory
  67 ----------------
  68
  69 There are 2 make's command-line variables 'O' and 'DESTDIR' that setup
  70 appropriate dirs:
  71 'O' - build directory
  72 'DESTDIR' - installation directory. This variable could also be setup in
  73 the 'CONFIGURATION' block of the "Makefile"
  74
  75 build
  76 -----
  77
  78 $ make O=<your_custom_build_catalog>
  79
  80 Example:
  81 $ make O=/home/hedin/prj/cpupower/build
  82
  83 install
  84 -------
  85
  86 $ make O=<your_custom_build_catalog> DESTDIR=<your_custom_install_catalog>
  87
  88 Example:
  89 $ make O=/home/hedin/prj/cpupower/build DESTDIR=/home/hedin/prj/cpupower \
  90 > install
  91
  92 Notice that both variables 'O' and 'DESTDIR' have been provided. The reason
  93 is that the build results are saved in the custom output dir defined by 'O'
  94 variable. So, this dir is the source for the installation step. If only
  95 'DESTDIR' were provided then the 'install' target would assume that the
  96 build directory is the current one, build everything there and install
  97 from the current dir.
  98
  99 The files will be installed to the following dirs:
 100
 101 -----------------------------------------------------------------------
 102 | Installing file        |               System dir                   |
 103 -----------------------------------------------------------------------
 104 | libcpupower            | ${DESTDIR}/usr/lib                         |
 105 -----------------------------------------------------------------------
 106 | cpupower               | ${DESTDIR}/usr/bin                         |
 107 -----------------------------------------------------------------------
 108 | cpufreq-bench_plot.sh  | ${DESTDIR}/usr/bin                         |
 109 -----------------------------------------------------------------------
 110 | man pages              | ${DESTDIR}/usr/man                         |
 111 -----------------------------------------------------------------------
 112
 113 If you look at the table for the default 'make' output dirs you will
 114 notice that the only difference with the non-default case is the
 115 ${DESTDIR} prefix. So, the structure of the output dirs remains the same
 116 regardles of the root output directory.
 117
 118
 119 clean and uninstall
 120 -------------------
 121
 122 'clean' target is intended for cleanup the build catalog from build results
 123 'uninstall' target is intended for removing installed files from the
 124 installation directory
 125
 126 default directory
 127 -----------------
 128
 129 This case is a straightforward one:
 130 $ make clean
 131 $ make uninstall
 132
 133 custom directory
 134 ----------------
 135
 136 Use 'O' command line variable to remove previously built files from the
 137 build dir:
 138 $ make O=<your_custom_build_catalog> clean
 139
 140 Example:
 141 $ make O=/home/hedin/prj/cpupower/build clean
 142
 143 Use 'DESTDIR' command line variable to uninstall previously installed files
 144 from the given dir:
 145 $ make DESTDIR=<your_custom_install_catalog>
 146
 147 Example:
 148 make DESTDIR=/home/hedin/prj/cpupower uninstall
 149
 150
 151 running the tool
 152 ----------------
 153
 154 default directory
 155 -----------------
 156
 157 $ sudo cpupower
 158
 159 custom directory
 160 ----------------
 161
 162 When it comes to run the utility from the custom build catalog things
 163 become a little bit complicated as 'just run' approach doesn't work.
 164 Assuming that the current dir is '<your_custom_install_catalog>/usr',
 165 issuing the following command:
 166
 167 $ sudo ./bin/cpupower
 168 will produce the following error output:
 169 ./bin/cpupower: error while loading shared libraries: libcpupower.so.1:
 170 cannot open shared object file: No such file or directory
 171
 172 The issue is that binary cannot find the 'libcpupower' library. So, we
 173 shall point to the lib dir:
 174 sudo LD_LIBRARY_PATH=lib64/ ./bin/cpupower
 175
 176
 177 THANKS
 178 ------
 179 Many thanks to Mattia Dongili who wrote the autotoolization and
 180 libtoolization, the manpages and the italian language file for cpupower;
 181 to Dave Jones for his feedback and his dump_psb tool; to Bruno Ducrot for his
 182 powernow-k8-decode and intel_gsic tools as well as the french language file;
 183 and to various others commenting on the previous (pre-)releases of
 184 cpupower.
 185
 186
 187         Dominik Brodowski