Mike Dodd | 8cfa702 | 2010-11-17 11:12:26 -0800 | [diff] [blame] | 1 | .TH OPCONTROL 1 "@DATE@" "oprofile @VERSION@" |
| 2 | .UC 4 |
| 3 | .SH NAME |
| 4 | opcontrol \- control OProfile profiling |
| 5 | .SH SYNOPSIS |
| 6 | .br |
| 7 | .B opcontrol |
| 8 | [ |
| 9 | .I options |
| 10 | ] |
| 11 | .SH DESCRIPTION |
| 12 | .B opcontrol |
| 13 | can be used to start profiling, end a profiling session, |
| 14 | dump profile data, and set up the profiling parameters. |
| 15 | |
| 16 | .SH OPTIONS |
| 17 | .TP |
| 18 | .BI "--help" |
| 19 | Show help message. |
| 20 | .br |
| 21 | .TP |
| 22 | .BI "--version" |
| 23 | Show version. |
| 24 | .br |
| 25 | .TP |
| 26 | .BI "--list-events" |
| 27 | Shows the monitorable events. |
| 28 | .br |
| 29 | .TP |
| 30 | .BI "--init" |
| 31 | Load the OProfile module if required and make the OProfile driver |
| 32 | interface available. |
| 33 | .br |
| 34 | .TP |
| 35 | .BI "--setup" |
| 36 | Followed by list options for profiling setup. Store setup |
| 37 | in ~root/.oprofile/daemonrc. Optional. |
| 38 | .br |
| 39 | .TP |
| 40 | .BI "--status" |
| 41 | Show configuration information. |
| 42 | .br |
| 43 | .TP |
| 44 | .BI "--start-daemon" |
| 45 | Start the oprofile daemon without starting profiling. Not available |
| 46 | in 2.2/2.4 kernels. |
| 47 | .br |
| 48 | .TP |
| 49 | .BI "--start" |
| 50 | Start data collection with either arguments provided by --setup |
| 51 | or with information saved in ~root/.oprofile/daemonrc. |
| 52 | .br |
| 53 | .TP |
| 54 | .BI "--dump" |
| 55 | Force a flush of the collected profiling data to the daemon. |
| 56 | .br |
| 57 | .TP |
| 58 | .BI "--stop" |
| 59 | Stop data collection. Not available in 2.2/2.4 kernels. |
| 60 | .br |
| 61 | .TP |
| 62 | .BI "--shutdown" |
| 63 | Stop data collection and kill the daemon. |
| 64 | .br |
| 65 | .TP |
| 66 | .BI "--reset" |
| 67 | Clear out data from current session, but leaves saved sessions. |
| 68 | .br |
| 69 | .TP |
| 70 | .BI "--save="sessionname |
| 71 | Save data from current session to sessionname. |
| 72 | .br |
| 73 | .TP |
| 74 | .BI "--deinit" |
| 75 | Shut down daemon. Unload the oprofile module and oprofilefs. |
| 76 | .br |
| 77 | .TP |
| 78 | .BI "--session-dir="dir_path |
| 79 | Use sample database out of directory dir_path instead of the default location (/var/lib/oprofile). |
| 80 | .br |
| 81 | .TP |
| 82 | .BI "--buffer-size="num |
Jeff Brown | 7a33c86 | 2011-02-02 14:00:44 -0800 | [diff] [blame] | 83 | Set kernel buffer to num samples. When using a 2.6 kernel, buffer watershed needs |
Mike Dodd | 8cfa702 | 2010-11-17 11:12:26 -0800 | [diff] [blame] | 84 | to be tweaked when changing this value. |
Jeff Brown | 7a33c86 | 2011-02-02 14:00:44 -0800 | [diff] [blame] | 85 | Rules: A non-zero value goes into effect after a '--shutdown/start' sequence. |
| 86 | A value of zero sets this parameter back to default value, but does not go into |
| 87 | effect until after '--deinit/init' sequence. |
Mike Dodd | 8cfa702 | 2010-11-17 11:12:26 -0800 | [diff] [blame] | 88 | .br |
| 89 | .TP |
| 90 | .BI "--buffer-watershed="num |
Jeff Brown | 7a33c86 | 2011-02-02 14:00:44 -0800 | [diff] [blame] | 91 | Set kernel buffer watershed to num samples (2.6 only). When |
| 92 | buffer-size - buffer-watershed free entries remain in the kernel buffer, data will be |
| 93 | flushed to the daemon. Most useful values are in the range [0.25 - 0.5] * buffer-size. |
| 94 | Same rules as defined for buffer-size. |
Mike Dodd | 8cfa702 | 2010-11-17 11:12:26 -0800 | [diff] [blame] | 95 | .br |
| 96 | .TP |
| 97 | .BI "--cpu-buffer-size="num |
| 98 | Set kernel per cpu buffer to num samples (2.6 only). If you profile at high |
| 99 | rate it can help to increase this if the log file show excessive count of |
Jeff Brown | 7a33c86 | 2011-02-02 14:00:44 -0800 | [diff] [blame] | 100 | sample lost cpu buffer overflow. Same rules as defined for buffer-size. |
Mike Dodd | 8cfa702 | 2010-11-17 11:12:26 -0800 | [diff] [blame] | 101 | .br |
| 102 | .TP |
| 103 | .BI "--event="[event|"default"] |
| 104 | Specify an event to measure for the hardware performance counters, |
| 105 | or "default" for the default event. The event is of the form |
| 106 | "CPU_CLK_UNHALTED:30000:0:1:1" where the numeric values are |
| 107 | count, unit mask, kernel-space counting, user-space counting, |
| 108 | respectively. Note that this over-rides all previous events selected; |
| 109 | if you want two or more counters used simultaneously, you must specify |
| 110 | them on the same opcontrol invocation. |
| 111 | .br |
| 112 | .TP |
| 113 | .BI "--separate="[none,lib,kernel,thread,cpu,all] |
| 114 | Separate samples based on the given separator. 'lib' separates |
| 115 | dynamically linked library samples per application. 'kernel' separates |
| 116 | kernel and kernel module samples per application; 'kernel' |
| 117 | implies 'library'. 'thread' gives separation for each thread and |
| 118 | task. 'cpu' separates for each CPU. 'all' implies all of the above |
| 119 | options and 'none' turns off separation. |
| 120 | .br |
| 121 | .TP |
| 122 | .BI "--callgraph=#depth" |
| 123 | Enable callgraph sample collection with a maximum depth. Use 0 to disable |
| 124 | callgraph profiling. This option is available on x86 using a |
| 125 | 2.6+ kernel with callgraph support enabled. It is also available on PowerPC using a 2.6.17+ kernel. |
| 126 | .br |
| 127 | .TP |
| 128 | .BI "--image="[name,name...|"all"] |
| 129 | Only profile the given absolute paths to binaries, or "all" to profile |
| 130 | everything (the default). |
| 131 | .br |
| 132 | .TP |
| 133 | .BI "--vmlinux="file |
| 134 | vmlinux kernel image. |
| 135 | .br |
| 136 | .TP |
| 137 | .BI "--no-vmlinux" |
| 138 | Use this when you don't have a kernel vmlinux file, and you don't want to |
| 139 | profile the kernel. |
| 140 | .br |
| 141 | .TP |
| 142 | .BI "--verbose" |
| 143 | Be verbose in the daemon log. This has a high overhead. |
| 144 | .br |
| 145 | .TP |
| 146 | .BI "--kernel-range="start,end |
| 147 | Set kernel range vma address in hexadecimal. |
| 148 | |
| 149 | .SH OPTIONS (specific to Xen) |
| 150 | .TP |
| 151 | .BI "--xen="file |
| 152 | Xen image |
| 153 | .br |
| 154 | .TP |
| 155 | .BI "--active-domains="<list> |
| 156 | List of domain ids participating in a multi-domain profiling session. If |
| 157 | more than one domain is specified in <list> they should be separated using |
| 158 | commas. This option can only be used in domain 0 which is the only domain |
| 159 | that can coordinate a multi-domain profiling session. Including domain 0 in |
| 160 | the list of active domains is optional. (e.g. --active-domains=2,5,6 and |
| 161 | --active-domains=0,2,5,6 are equivalent) |
| 162 | .br |
| 163 | |
| 164 | .SH ENVIRONMENT |
| 165 | No special environment variables are recognised by opcontrol. |
| 166 | |
| 167 | .SH FILES |
| 168 | .TP |
| 169 | .I /root/.oprofile/daemonrc |
| 170 | Configuration file for opcontrol |
| 171 | .TP |
| 172 | .I /var/lib/oprofile/samples/ |
| 173 | The location of the generated sample files. |
| 174 | |
| 175 | .SH VERSION |
| 176 | .TP |
| 177 | This man page is current for @PACKAGE@-@VERSION@. |
| 178 | |
| 179 | .SH SEE ALSO |
| 180 | .BR @OP_DOCDIR@, |
| 181 | .BR oprofile(1) |