[0d0e60]: doc / oprofile.xml  Maximize  Restore  History

Download this file

2041 lines (1921 with data), 88.4 kB

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book id="oprofile-guide">
<bookinfo>
<title>OProfile manual</title>
<authorgroup>
<author>
<firstname>John</firstname>
<surname>Levon</surname>
<affiliation>
<address><email>levon@movementarian.org</email></address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2000-2003</year>
<holder>Victoria University of Manchester, John Levon and others</holder>
</copyright>
</bookinfo>
<toc></toc>
<chapter id="introduction">
<title>Introduction</title>
<para>
This manual applies to OProfile version <oprofileversion />.
OProfile is a profiling system for Linux 2.2/2.4/2.6 systems on a number of architectures. It is capable of profiling
all parts of a running system, from the kernel (including modules and interrupt handlers) to shared libraries
to binaries. It runs transparently in the background collecting information at a low overhead. These
features make it ideal for profiling entire systems to determine bottle necks in real-world systems.
</para>
<para>
Many CPUs provide "performance counters", hardware registers that can count "events"; for example,
cache misses, or CPU cycles. OProfile provides profiles of code based on the number of these occurring events:
repeatedly, every time a certain (configurable) number of events has occurred, the PC value is recorded.
This information is aggregated into profiles for each binary image.</para>
<para>
Some hardware setups do not allow OProfile to use performance counters: in these cases, no
events are available, and OProfile operates in timer/RTC mode, as described in later chapters.
</para>
<sect1 id="applications">
<title>Applications of OProfile</title>
<para>
OProfile is useful in a number of situations. You might want to use OProfile when you :
</para>
<itemizedlist>
<listitem><para>need low overhead</para></listitem>
<listitem><para>cannot use highly intrusive profiling methods</para></listitem>
<listitem><para>need to profile interrupt handlers</para></listitem>
<listitem><para>need to profile an application and its shared libraries</para></listitem>
<listitem><para>need to capture the performance behaviour of entire system</para></listitem>
<listitem><para>want to examine hardware effects such as cache misses</para></listitem>
<listitem><para>want detailed source annotation</para></listitem>
<listitem><para>want instruction-level profiles</para></listitem>
</itemizedlist>
<para>
OProfile is not a panacea. OProfile might not be a complete solution when you :
</para>
<itemizedlist>
<listitem><para>require call graph profiles</para></listitem>
<listitem><para>don't have root permissions</para></listitem>
<listitem><para>require 100% instruction-accurate profiles</para></listitem>
<listitem><para>need function call counts or an interstitial profiling API</para></listitem>
<listitem><para>cannot tolerate any disturbance to the system whatsoever</para></listitem>
<listitem><para>need to profile interpreted or dynamically compiled code such as Java or Python</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="requirements">
<title>System requirements</title>
<variablelist>
<varlistentry>
<term>Linux kernel 2.2/2.4/2.6</term>
<listitem><para>
OProfile uses a kernel module that can be compiled for
2.2.11 or later and 2.4. Versions 2.4.10 or above are recommended, and required if you use the
boot-time kernel option <option>nosmp</option>. AMD64 processors support requires a recent (&gt;= 2.4.19) kernel
with the line <constant>EXPORT_SYMBOL(do_fork);</constant> present in <filename>kernel/ksyms.c</filename>.
Such a kernel is present in the <ulink url="http://www.x86-64.org">x86-64.org</ulink> CVS repository.
2.6 kernels are supported with the in-kernel OProfile driver.
<!-- FIXME: do we require always gte 2.4.10 for nosmp ? -->
</para></listitem>
</varlistentry>
<varlistentry>
<term>modutils 2.4.6 or above</term>
<listitem><para>
You should have installed modutils 2.4.6 or higher (in fact earlier versions work well in almost all
cases).
</para></listitem>
</varlistentry>
<varlistentry>
<term>Supported architecture</term>
<listitem><para>
For Intel IA32, a CPU with either a P6 generation or Pentium 4 core is
required. In marketing terms this translates to anything
between an Intel Pentium Pro (not Pentium Classics) and
a Pentium 4 / Xeon, including all Celerons. The AMD
Athlon, Duron, and Hammer CPUs are also supported. Other IA32
CPU types only support the RTC mode of OProfile; please
see later in this manual for details. Hyper-threaded Pentium IVs
are not supported in 2.4. For 2.4 kernels, the Intel
IA-64 CPUs are also supported. For 2.6 kernels, there is additionally
support for Alpha processors, and sparc64, ppc64, and PA-RISC in
timer mode.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Uniprocessor or SMP</term>
<listitem><para>
SMP machines are fully supported.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Required libraries</term>
<listitem><para>
These libraries are required : <filename>popt</filename>, <filename>bfd</filename>,
<filename>liberty</filename> (debian users: libiberty is provided in binutils-dev package), <filename>dl</filename>,
plus the standard C++ libraries.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Bash version 2</term>
<listitem><para>
The <command>opcontrol</command> script requires bash version 2 at least to be installed
as <filename>/bin/bash</filename> or <filename>/bin/bash2</filename>
</para></listitem>
</varlistentry>
<varlistentry>
<term>OProfile GUI</term>
<listitem><para>
The use of the GUI to start the profiler requires the <filename>Qt 2</filename> library. <filename>Qt 3</filename> should
also work.
</para></listitem>
</varlistentry>
<varlistentry>
<term><acronym>ELF</acronym></term>
<listitem><para>
Probably not too strenuous a requirement, but older <acronym>A.OUT</acronym> binaries/libraries are not supported.
</para></listitem>
</varlistentry>
<varlistentry>
<term>K&amp;R coding style</term>
<listitem><para>
OK, so it's not really a requirement, but I wish it was...
</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="resources">
<title>Internet resources</title>
<variablelist>
<varlistentry>
<term>Web page</term>
<listitem><para>
There is a web page (which you may be reading now) at
<ulink url="http://oprofile.sf.net/">http://oprofile.sf.net/</ulink>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Download</term>
<listitem><para>
You can download a source tarball or get anonymous CVS at the sourceforge page,
<ulink url="http://sf.net/projects/oprofile/">http://sf.net/projects/oprofile/</ulink>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Mailing list</term>
<listitem><para>
There is a low-traffic OProfile-specific mailing list, details at
<ulink url="http://sf.net/mail/?group_id=16191">http://sf.net/mail/?group_id=16191</ulink>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Bug tracker</term>
<listitem><para>
There is a bug tracker for OProfile at SourceForge,
<ulink url="http://sf.net/tracker/?group_id=16191&amp;atid=116191">http://sf.net/tracker/?group_id=16191&amp;atid=116191</ulink>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>IRC channel</term>
<listitem><para>
Several OProfile developers and users sometimes hang out on channel <command>#oprofile</command>
on the <ulink url="http://freenode.info">freenode</ulink> network.
</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="install">
<title>Installation</title>
<para>
First you need to build OProfile and install it. <command>./configure</command>, <command>make</command>, <command>make install</command>
is often all you need, but note these arguments to <command>./configure</command> :
</para>
<variablelist>
<varlistentry>
<term><option>--with-linux</option></term>
<listitem><para>
Use this option to specify the location of the kernel source tree you wish
to compile against. The kernel module is built against this source and
will only work with a running kernel built from the same source with
exact same options, so it is important you specify this option if you need
to.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--with-kernel-support</option></term>
<listitem><para>
Use this option with 2.6 and above kernels to indicate the
kernel provides the OProfile device driver.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--with-qt-dir/includes/libraries</option></term>
<listitem><para>
Specify the location of Qt headers and libraries. It defaults to searching in
<constant>$QTDIR</constant> if these are not specified.
</para></listitem>
</varlistentry>
<varlistentry id="enable-abi">
<term><option>--enable-abi</option></term>
<listitem><para>
Activate code within the OProfile sample collection daemon
<command>oprofiled</command> which records information about the binary
format of sample files in <filename>/var/lib/oprofile/abi</filename>, to
permit their transport between hosts using the
<command>op_import</command> utility. See <xref
linkend="op-import" />. This option is primarily intended for embedded
systems or remote analysis of production machines; if you will be
performing all sample analysis on the same machine as you are profiling,
it is safe to omit this option.
</para></listitem>
</varlistentry>
<varlistentry id="disable-werror">
<term><option>--disable-werror</option></term>
<listitem><para>
Development versions of OProfile build by
default with <option>-Werror</option>. This option turns
<option>-Werror</option> off.
</para></listitem>
</varlistentry>
<varlistentry id="disable-optimization">
<term><option>--disable-optimization</option></term>
<listitem><para>
Disable the <option>-O2</option> compiler flag
(useful if you discover an OProfile bug and want to give a useful
back-trace etc.)
</para></listitem>
</varlistentry>
</variablelist>
<para>
You'll need to have a configured kernel source for the current kernel
to build the module for 2.4 kernels. Since all distributions provide different kernels it's unlikely the running kernel match the configured source
you installed. The safest way is to recompile your own kernel, run it and compile oprofile. It is also recommended that if you have a
uniprocessor machine, you enable the local APIC / IO_APIC support for
your kernel (this is automatically enabled for SMP kernels). On
machines with power management, such as laptops, the power management
must be turned off when using OProfile with 2.4 kernels. The power management software
in the BIOS cannot handle the non-maskable interrupts (NMIs) used by
OProfile for data collection. If you use the NMI watchdog, be aware that
the watchdog is disabled when profiling starts, and not re-enabled until the
OProfile module is removed (or, in 2.6, when OProfile is not running). If you compile OProfile for
a 2.2 kernel you must be root to compile the module. If you are using
2.6 kernels or higher, you do not need kernel source, as long as the
OProfile driver is enabled; additionally, you should not need to disable
power management.
</para>
<para>
Please note that you must save or have available the <filename>vmlinux</filename> file
generated during a kernel compile, as OProfile needs it (you can use
<option>--no-vmlinux</option>, but this will prevent kernel profiling).
</para>
</sect1>
<sect1 id="uninstall">
<title>Uninstalling OProfile</title>
<para>
You must have the source tree available to uninstall OProfile; a <command>make uninstall</command> will
remove all installed files except your configuration file in the directory <filename>~/.oprofile</filename>.
</para>
</sect1>
</chapter>
<chapter id="overview">
<title>Overview</title>
<sect1 id="getting-started">
<title>Getting started</title>
<para>
Before you can use OProfile, you must set it up. The minimum setup required for this
is to tell OProfile where the <filename>vmlinux</filename> file corresponding to the
running kernel is, for example :
</para>
<screen>opcontrol --vmlinux=/boot/vmlinux-`uname -r`</screen>
<para>
If you don't want to profile the kernel itself,
you can tell OProfile you don't have a <filename>vmlinux</filename> file :
</para>
<screen>opcontrol --no-vmlinux</screen>
<para>
Now we are ready to start the daemon (<command>oprofiled</command>) which collects
the profile data :
</para>
<screen>opcontrol --start</screen>
<para>
When I want to stop profiling, I can do so with :
</para>
<screen>opcontrol --shutdown</screen>
<para>
Note that unlike <command>gprof</command>, no instrumentation (<option>-pg</option>
and <option>-a</option> options to <command>gcc</command>)
is necessary.
</para>
<para>
Periodically (or on <command>opcontrol --shutdown</command> or <command>opcontrol --dump</command>)
the profile data is written out into the <filename>/var/lib/oprofile/samples</filename> directory.
These profile files cover shared libraries, applications, the kernel (vmlinux), and kernel modules.
You can clear the profile data (at any time) with <command>opcontrol --reset</command>.
</para>
<para>
You can get summaries of this data in a number of ways at any time. To get a summary of
data across the entire system for all of these profiles, you can do :
</para>
<screen>opreport</screen>
<para>
Or to get a more detailed summary, for a particular image, you can do something like :
</para>
<screen>opreport -l /boot/vmlinux-`uname -r`</screen>
<para>
There are also a number of other ways of presenting the data, as described later in this manual.
Note that OProfile will choose a default profiling setup for you. However, there are a number
of options you can pass to <command>opcontrol</command> if you need to change something,
also detailed later.
</para>
</sect1>
<sect1 id="tools-overview">
<title>Tools summary</title>
<para>
This section gives a brief description of the available OProfile utilities and their purpose.
</para>
<variablelist>
<varlistentry>
<term><filename>op_help</filename></term>
<listitem><para>
This utility lists the available events and short descriptions.
</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>opcontrol</filename></term>
<listitem><para>
Used for controlling the OProfile data collection, discussed in <xref linkend="controlling" />.
</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>opreport</filename></term>
<listitem><para>
This is the main tool for retrieving useful profile data, described in
<xref linkend="opreport" />.
</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>opannotate</filename></term>
<listitem><para>
This utility can be used to produce annotated source, assembly or mixed source/assembly.
Source level annotation is available only if the application was compiled with
debugging symbols. See <xref linkend="opannotate" />.
</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>opgprof</filename></term>
<listitem><para>
This utility can output gprof-style data files for a binary, for use with
<command>gprof -p</command>. See <xref linkend="opgprof" />.
</para></listitem>
</varlistentry>
<varlistentry id="op-import">
<term><filename>op_import</filename></term>
<listitem><para>
This utility converts sample database files from a foreign binary format (abi) to
the native format. This is useful only when moving sample files between hosts,
for analysis on platforms other than the one used for collection. The abi format
of the file to be imported is described in a text file located in
<filename>/var/lib/oprofile/abi</filename>, if the <option>--enable-abi</option>
configure-time option was enabled. Furthermore, the <command>op_import</command>
tool is not built unless <option>--enable-abi</option> is given. See <xref
linkend="enable-abi" />.
</para></listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="controlling">
<title>Controlling the profiler</title>
<sect1 id="controlling-daemon">
<title>Using <command>opcontrol</command></title>
<para>
In this section we describe the configuration and control of the profiling system
with opcontrol in more depth.
The <command>opcontrol</command> script has a default setup, but you
can alter this with the options given below. In particular,
if your hardware supports performance counters, you can configure them.
There are a number of counters (for example, counter 0 and counter 1
on the Pentium III). Each of these counters can be programmed with
an event to count, such as cache misses or MMX operations. The event
chosen for each counter is reflected in the profile data collected
by OProfile: functions and binaries at the top of the profiles reflect
that most of the chosen events happened within that code.
</para>
<para>
Additionally, each counter has a "count" value: this corresponds to how
detailed the profile is. The lower the value, the more frequently profile
samples are taken. A counter can choose to sample only kernel code, user-space code,
or both (both is the default). Finally, some events have a "unit mask"
- this is a value that further restricts the types of event that are counted.
The event types and unit masks for your CPU are listed by <command>opcontrol
--list-events</command>.
</para>
<para>
The <command>opcontrol</command> script provides the following actions :
</para>
<variablelist>
<varlistentry>
<term><option>--init</option></term>
<listitem><para>
Loads the OProfile module if required and makes the OProfile driver
interface available.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--setup</option></term>
<listitem><para>
Followed by list arguments for profiling set up. List of arguments
saved in <filename>/root/.oprofile/daemonrc</filename>.
Giving this option is not necessary; you can just directly pass one
of the setup options, e.g. <command>opcontrol --no-vmlinux</command>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--start-daemon</option></term>
<listitem><para>
Start the oprofile daemon without starting actual profiling. The profiling
can then be started using <option>--start</option>. This is useful for avoiding
measuring the cost of daemon startup, as <option>--start</option> is a simple
write to a file in oprofilefs. Not available in 2.2/2.4 kernels.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--start</option></term>
<listitem><para>
Start data collection with either arguments provided by <option>--setup</option>
or information saved in <filename>/root/.oprofile/daemonrc</filename>. Specifying
the addition <option>--verbose</option> makes the daemon generate lots of debug data
whilst it is running.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--dump</option></term>
<listitem><para>
Force a flush of the collected profiling data to the daemon.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--stop</option></term>
<listitem><para>
Stop data collection (this separate step is not possible with 2.2 or 2.4 kernels).
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--shutdown</option></term>
<listitem><para>
Stop data collection and kill the daemon.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reset</option></term>
<listitem><para>
Clears out data from current session, but leaves saved sessions.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--save=</option>session_name</term>
<listitem><para>
Save data from current session to session_name.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--deinit</option></term>
<listitem><para>
Shuts down daemon. Unload the OProfile module and oprofilefs.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-events</option></term>
<listitem><para>
List event types and unit masks.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--help</option></term>
<listitem><para>
Generate usage messages.
</para></listitem>
</varlistentry>
</variablelist>
<para>
There are a number of possible settings, of which, only
<option>--vmlinux</option> (or <option>--no-vmlinux</option>)
is required. These settings are stored in <filename>~/.oprofile/daemonrc</filename>.
</para>
<variablelist>
<varlistentry>
<term><option>--buffer-size=</option>num</term>
<listitem><para>
Number of samples in kernel buffer.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--event=</option>[eventspec]</term>
<listitem><para>
Use the given performance counter event to profile.
See <xref linkend="eventspec" /> below.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--separate=</option>[none,library,kernel,thread,cpu,all]</term>
<listitem><para>
By default, every profile is stored in a single file. Thus, for example,
samples in the C library are all accredited to the <filename>/lib/libc.o</filename>
profile. However, you choose to create separate sample files by specifying
one of the below options.
</para>
<informaltable frame="all">
<tgroup cols='2'>
<tbody>
<row><entry><option>none</option></entry><entry>No profile separation (default)</entry></row>
<row><entry><option>library</option></entry><entry>Create per-application profiles for libraries</entry></row>
<row><entry><option>kernel</option></entry><entry>Create per-application profiles for the kernel and kernel modules</entry></row>
<row><entry><option>thread</option></entry><entry>Create profiles for each thread and each task</entry></row>
<row><entry><option>cpu</option></entry><entry>Create profiles for each CPU</entry></row>
<row><entry><option>all</option></entry><entry>All of the above options</entry></row>
</tbody>
</tgroup>
</informaltable>
<para>
Note that <option>--separate=kernel</option> also turns on <option>--separate=library</option>.
<!-- FIXME: update if this change -->
When using <option>--separate=kernel</option>, samples in hardware interrupts, soft-irqs, or other
asynchronous kernel contexts are credited to the task currently running. This means you will see
seemingly nonsense profiles such as <filename>/bin/bash</filename> showing samples for the PPP modules,
etc.
</para>
<para>
On 2.2/2.4 only kernel threads already started when profiling begins are correctly profiled;
newly started kernel thread samples are credited to the vmlinux (kernel) profile.
</para>
<para>
Using <option>--separate=thread</option> creates a lot
of sample files if you leave OProfile running for a while; it's most
useful when used for short sessions, or when using image filtering.
</para>
</listitem>
<varlistentry>
<term><option>--callgraph=</option>#depth</term>
<listitem><para>
Enable callgraph sample collection with a maximum depth. Use 0
to disable callgraph. This option is ignored with 2.2/2.4 or
2.6 kernel w/o the callgraph support patch (x86 only).
</para></listitem>
</varlistentry>
</varlistentry>
<term><option>--image=</option>image,[images]|"all"</term>
<listitem><para>
Image filtering. If you specify one or more absolute
paths to binaries, OProfile will only produce profile results for those
binary images. This is useful for restricting the sometimes voluminous
output you may get otherwise, especially with
<option>--separate=thread</option>. Note that if you are using
<option>--separate=library</option> or
<option>--separate=kernel</option>, then if you specification an
application binary, the shared libraries and kernel code
<emphasis>are</emphasis> included. Specify the value
"all" to profile everything (the default).
</para></listitem>
<varlistentry>
</varlistentry>
<varlistentry>
<term><option>--vmlinux=</option>file</term>
<listitem><para>
vmlinux kernel image.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--no-vmlinux</option></term>
<listitem><para>
Use this when you don't have a kernel vmlinux file, and you don't want
to profile the kernel. This still counts the total number of kernel samples,
but can't give symbol-based results for the kernel or any modules.
</para></listitem>
</varlistentry>
</variablelist>
<sect2 id="opcontrolexamples">
<title>Examples</title>
<sect3 id="examplesperfctr">
<title>Intel performance counter setup</title>
<para>
Here, we have a Pentium III running at 800MHz, and we want to look at where data memory
references are happening most, and also get results for CPU time.
</para>
<screen>
# opcontrol --event=CPU_CLK_UNHALTED:400000 --event=DATA_MEM_REFS:10000
# opcontrol --vmlinux=/boot/2.6.0/vmlinux
# opcontrol --start
</screen>
</sect3>
<sect3 id="examplesrtc">
<title>RTC mode</title>
<para>
Here, we have an Intel laptop without support for performance counters, running on 2.4 kernels.
</para>
<screen>
# op_help -r
CPU with RTC device
# opcontrol --vmlinux=/boot/2.6.0/vmlinux --event=RTC_INTERRUPTS:1024
# opcontrol --start
</screen>
</sect3>
<sect3 id="examplesstartdaemon">
<title>Starting the daemon separately</title>
<para>
If we're running 2.6 kernels, we can use <option>--start-daemon</option> to avoid
the profiler startup affecting results.
</para>
<screen>
# opcontrol --vmlinux=/boot/2.6.0/vmlinux
# opcontrol --start-daemon
# my_favourite_benchmark --init
# opcontrol --start ; my_favourite_benchmark --run ; opcontrol --stop
</screen>
</sect3>
<sect3 id="exampleseparate">
<title>Separate profiles for libraries and the kernel</title>
<para>
Here, we want to see a profile of the OProfile daemon itself, including when
it was running inside the kernel driver, and its use of shared libraries.
</para>
<screen>
# opcontrol --separate=kernel --vmlinux=/boot/2.6.0/vmlinux
# opcontrol --start
# my_favourite_stress_test --run
# opreport -l -p /lib/modules/2.6.0/kernel /usr/local/bin/oprofiled
</screen>
</sect3>
<sect3 id="examplessessions">
<title>Profiling sessions</title>
<para>
It can often be useful to split up profiling data into several different
time periods. For example, you may want to collect data on an application's
startup separately from the normal runtime data. You can use the simple
command <command>opcontrol --save</command> to do this. For example :
</para>
<screen>
# opcontrol --save=blah
</screen>
<para>
will create a sub-directory in <filename>/var/lib/oprofile/samples</filename> containing the samples
up to that point (the current session's sample files are moved into this
directory). You can then pass this session name as a parameter to the post-profiling
analysis tools, to only get data up to the point you named the
session. If you do not want to save a session, you can do
<command>rm -rf /var/lib/oprofile/samples/sessionname</command> or, for the
current session, <command>opcontrol --reset</command>.
</para>
</sect3>
</sect2>
<sect2 id="eventspec">
<title>Specifying performance counter events</title>
<para>
The <option>--event</option> option to <command>opcontrol</command>
takes a specification that indicates how the details of each
hardware performance counter should be setup. If you want to
revert to OProfile's default setting (<option>--event</option>
is strictly optional), use <option>--event=default</option>.
</para>
<para>
You can pass multiple event specifications. OProfile will allocate
hardware counters as necessary. Note that some combinations are not
allowed by the CPU; running <command>opcontrol --list-events</command> gives the details
of each event. The event specification is a colon-separated string
of the form <option><emphasis>name</emphasis>:<emphasis>count</emphasis>:<emphasis>unitmask</emphasis>:<emphasis>kernel</emphasis>:<emphasis>user</emphasis></option> as described in this table:
</para>
<informaltable frame="all">
<tgroup cols='2'>
<tbody>
<row><entry><option>name</option></entry><entry>The symbolic event name, e.g. <constant>CPU_CLK_UNHALTED</constant></entry></row>
<row><entry><option>count</option></entry><entry>The counter reset value, e.g. 100000</entry></row>
<row><entry><option>unitmask</option></entry><entry>The unit mask, as given in the events list, e.g. 0x0f</entry></row>
<row><entry><option>kernel</option></entry><entry>Whether to profile kernel code</entry></row>
<row><entry><option>user</option></entry><entry>Whether to profile userspace code</entry></row>
</tbody>
</tgroup>
</informaltable>
<para>
The last three values are optional, if you omit them (e.g. <option>--event=DATA_MEM_REFS:30000</option>),
they will be set to the default values (a unit mask of 0, and profiling both kernel and
userspace code). Note that some events require a unit mask.
</para>
<para>
If OProfile is using RTC mode, and you want to alter the default counter value,
you can use something like <option>--event=RTC_INTERRUPTS:2048</option>. Note the last
three values here are ignored.
If OProfile is using timer-interrupt mode, there is no configuration possible.
</para>
</sect2>
</sect1>
<sect1 id="oprofile-gui">
<title>Using <command>oprof_start</command></title>
<para>
The <command>oprof_start</command> application provides a convenient way to start the profiler.
Note that <command>oprof_start</command> is just a wrapper around the <command>opcontrol</command> script,
so it does not provide more services than the script itself.
</para>
<para>
After <command>oprof_start</command> is started you can select the event type for each counter;
the sampling rate and other related parameters are explained in <xref linkend="controlling-daemon" />.
The "Configuration" section allows you to set general parameters such as the buffer size, kernel filename
etc. The counter setup interface should be self-explanatory; <xref linkend="hardware-counters" /> and related
links contain information on using unit masks.
</para>
<para>
A status line shows the current status of the profiler: how long it has been running, and the average
number of interrupts received per second and the total, over all processors.
Note that quitting <command>oprof_start</command> does not stop the profiler.
</para>
<para>
Your configuration is saved in the same file as <command>opcontrol</command> uses; that is,
<filename>~/.oprofile/daemonrc</filename>.
</para>
</sect1>
<sect1 id="detailed-parameters">
<title>Configuration details</title>
<sect2 id="hardware-counters">
<title>Hardware performance counters</title>
<note>
<para>
Your CPU type may not include the requisite support for hardware performance counters, in which case
you must use OProfile in RTC mode in 2.4 (see <xref linkend="rtc" />), or timer mode in 2.6 (see <xref linkend="timer" />).
You do not really need to read this section unless you are interested in using
events other than the default event chosen by OProfile.
</para>
</note>
<para>
The hardware performance counters are detailed in the Intel IA-32 Architecture Manual, Volume 3, available
from <ulink url="http://developer.intel.com/">http://developer.intel.com/</ulink>. The AMD Athlon/Duron
implementation is detailed in <ulink url="http://www.amd.com/products/cpg/athlon/techdocs/pdf/22007.pdf">
http://www.amd.com/products/cpg/athlon/techdocs/pdf/22007.pdf</ulink>.
These processors are capable of delivering an interrupt when a counter overflows.
This is the basic mechanism on which OProfile is based. The delivery mode is <acronym>NMI</acronym>,
so blocking interrupts in the kernel does not prevent profiling. When the interrupt handler is called,
the current <acronym>PC</acronym> value and the current task are recorded into the profiling structure.
This allows the overflow event to be attached to a specific assembly instruction in a binary image.
The daemon receives this data from the kernel, and writes it to the sample files.
</para>
<para>
If we use an event such as <constant>CPU_CLK_UNHALTED</constant> or <constant>INST_RETIRED</constant>
(<constant>GLOBAL_POWER_EVENTS</constant> or <constant>INSTR_RETIRED</constant>, respectively, on the Pentium 4), we can
use the overflow counts as an estimate of actual time spent in each part of code. Alternatively we can profile interesting
data such as the cache behaviour of routines with the other available counters.
</para>
<para>
However there are several caveats. First, there are those issues listed in the Intel manual. There is a delay
between the counter overflow and the interrupt delivery that can skew results on a small scale - this means
you cannot rely on the profiles at the instruction level as being perfectly accurate.
If you are using an "event-mode" counter such as the cache counters, a count registered against it doesn't mean
that it is responsible for that event. However, it implies that the counter overflowed in the dynamic
vicinity of that instruction, to within a few instructions. Further details on this problem can be found in
<xref linkend="interpreting" /> and also in the Digital paper "ProfileMe: A Hardware Performance Counter".
</para>
<para>
Each counter has several configuration parameters.
First, there is the unit mask: this simply further specifies what to count.
Second, there is the counter value, discussed below. Third, there is a parameter whether to increment counts
whilst in kernel or user space. You can configure these separately for each counter.
</para>
<para>
After each overflow event, the counter will be re-initialized
such that another overflow will occur after this many events have been counted. Thus, higher
values mean less-detailed profiling, and lower values mean more detail, but higher overhead.
Picking a good value for this
parameter is, unfortunately, somewhat of a black art. It is of course dependent on the event
you have chosen.
Specifying too large a value will mean not enough interrupts are generated
to give a realistic profile (though this problem can be ameliorated by profiling for <emphasis>longer</emphasis>).
Specifying too small a value can lead to higher performance overhead.
</para>
</sect2>
<sect2 id="rtc">
<title>OProfile in RTC mode</title>
<note><para>
This section applies to 2.2/2.4 kernels only.
</para></note>
<para>
Some CPU types do not provide the needed hardware support to use the hardware performance counters. This includes
some laptops, classic Pentiums, and other CPU types not yet supported by OProfile (such as Cyrix).
On these machines, OProfile falls
back to using the real-time clock interrupt to collect samples. This interrupt is also used by the <command>rtc</command>
module: you cannot have both the OProfile and rtc modules loaded nor the rtc support compiled in the kernel.
</para>
<para>
RTC mode is less capable than the hardware counters mode; in particular, it is unable to profile sections of
the kernel where interrupts are disabled. There is just one available event, "RTC interrupts", and its value
corresponds to the number of interrupts generated per second (that is, a higher number means a better profiling
resolution, and higher overhead). The current implementation of the real-time clock supports only power-of-two
sampling rates from 2 to 4096 per second. Other values within this range are rounded to the nearest power of
two.
</para>
<para>
Setting the value from the GUI should be straightforward. On the command line, you need to specify the
event to <command>opcontrol</command>, e.g. :
</para>
<para><command>opcontrol --event=RTC_INTERRUPTS:256</command></para>
</sect2>
<sect2 id="timer">
<title>OProfile in timer interrupt mode</title>
<note><para>
This section applies to 2.6 kernels and above only.
</para></note>
<para>
In 2.6 kernels on CPUs without OProfile support for the hardware performance counters, the driver
falls back to using the timer interrupt for profiling. Like the RTC mode in 2.4 kernels, this is not able to
profile code that has interrupts disabled. Note that there are no configuration parameters for
setting this, unlike the RTC and hardware performance counter setup.
</para>
<para>
You can force use of the timer interrupt by using the <option>timer=1</option> module
parameter (or <option>oprofile.timer=1</option> on the boot command line if OProfile is
built-in).
</para>
</sect2>
<sect2 id="p4">
<title>Pentium 4 support</title>
<para>
The Pentium 4 / Xeon performance counters are organized around 3 types of model specific registers (MSRs): 45 event
selection control registers (ESCRs), 18 counter configuration control registers (CCCRs) and 18 counters. ESCRs describe a
particular set of events which are to be recorded, and CCCRs bind ESCRs to counters and configure their
operation. Unfortunately the relationship between these registers is quite complex; they cannot all be used with one
another at any time. There is, however, a subset of 8 counters, 8 ESCRs, and 8 CCCRs which can be used independently of
one another, so OProfile only accesses those registers, treating them as a bank of 8 "normal" counters, similar
to those in the P6 or Athlon families of CPU.
</para>
<para>
There is currently no support for Precision Event-Based Sampling (PEBS), nor any advanced uses of the Debug Store
(DS). Current support is limited to the conservative extension of OProfile's existing interrupt-based model described
above. Performance monitoring hardware on Pentium 4 / Xeon processors with Hyperthreading enabled (multiple logical
processors on a single die) is not supported in 2.4 kernels (you can use OProfile if you disable hyper-threading,
though).
</para>
</sect2>
<sect2 id="ia64">
<title>Intel Itanium 2 support</title>
<para>
The Itanium 2 performance monitoring unit (PMU) organizes the counters as four
pairs of performance event monitoring registers. Each pair is composed of a
Performance Monitoring Configuration (PMC) register and Performance Monitoring
Data (PMD) register. The PMC selects the performance event being monitored and
the PMD determines the sampling interval. The IA64 Performance Monitoring Unit
(PMU) triggers sampling with maskable interrupts. Thus, samples will not occur
in sections of the IA64 kernel where interrupts are disabled.
</para>
<para>
None of the advance features of the Itanium 2 performance monitoring unit
such as opcode matching, address range matching, or precise event sampling are
supported by this version of OProfile. The Itanium 2 support only maps OProfile's
existing interrupt-based model to the PMU hardware.
</para>
</sect2>
<sect2 id="misuse">
<title>Dangerous counter settings</title>
<para>
OProfile is a low-level profiler which allow continuous profiling with a low-overhead cost.
If too low a count reset value is set for a counter, the system can become overloaded with counter
interrupts, and seem as if the system has frozen. Whilst some validation is done, it
is not foolproof.
</para>
<note><para>
This can happen as follows: When the profiler count
reaches zero an NMI handler is called which stores the sample values in an internal buffer, then resets the counter
to its original value. If the count is very low, a pending NMI can be sent before the NMI handler has
completed. Due to the priority of the NMI, the local APIC delivers the pending interrupt immediately after
completion of the previous interrupt handler, and control never returns to other parts of the system.
In this way the system seems to be frozen.
</para></note>
<para>If this happens, it will be impossible to bring the system back to a workable state.
There is no way to provide real security against this happening, other than making sure to use a reasonable value
for the counter reset. For example, setting <constant>CPU_CLK_UNHALTED</constant> event type with a ridiculously low reset count (e.g. 500)
is likely to freeze the system.
</para>
<para>
In short : <command>Don't try a foolish sample count value</command>. Unfortunately the definition of a foolish value
is really dependent on the event type - if ever in doubt, e-mail </para>
<address><email>oprofile-list@lists.sf.net</email>.</address>
</sect2>
</sect1>
<sect1 id="other-features">
<title>Other features</title>
<sect2 id="pidpgrpfilter">
<title>pid/pgrp filter</title>
<para>There are situations where you are only interested in the profiling results of a particular
running process, or process tty group. You can set
the pid/pgrp values via the <filename>--pid-filter</filename> and <filename>--pgrp-filter</filename>
options to <command>opcontrol</command>, which will make the daemon ignore samples for processes
that don't match the filter. These options are not available in 2.6 and above kernels.
</para>
</sect2>
<sect2 id="unloadable">
<title>Unloading the kernel module</title>
<note><para>
This section applies to 2.2/2.4 kernels only, OProfile in 2.6 can be unloaded safely.
</para></note>
<para>
The kernel module can be unloaded, but is designed to take very little memory when profiling is not underway.
There is no need to unload the module between profiler runs.
</para>
<para>
<command>lsmod</command> and similar utilities will still show the module's use count as <constant>-1</constant>.
However, this is not to be relied on - the module will become unloadable some short time after stopping profiling.
</para>
<para>
Note that by default module unloading is disabled when used on SMP systems. This is because of a small
chance of a module unload race crashing the kernel. As the race is very small, it is allowed to
re-enable the module unload by specifying the "allow_unload" parameter to the module :
</para>
<para><command>modprobe oprofile allow_unload=1</command></para>
<para>This option can be <emphasis>DANGEROUS</emphasis> and should only be used on non-production systems.</para>
</sect2>
</sect1>
</chapter>
<chapter id="results">
<title>Obtaining results</title>
<para>
OK, so the profiler has been running, but it's not much use unless we can get some data out. Fairly often,
OProfile does a little <emphasis>too</emphasis> good a job of keeping overhead low, and no data reaches
the profiler. This can happen on lightly-loaded machines. Remember you can force a dump at any time with :
</para>
<para><command>opcontrol --dump</command></para>
<para>Remember to do this before complaining there is no profiling data !
Now that we've got some data, it has to be processed. That's the job of <command>opreport</command>,
<command>opannotate</command>, or <command>opgprof</command>.
</para>
<sect1 id="opreport">
<title>Image summaries and symbol summaries</title>
<para>
The <command>opreport</command> utility is the primary utility you will use for
getting formatted data out of OProfile. It produces two types of data: image summaries
and symbol summaries. An image summary lists the number of samples for individual
binary images such as libraries or applications. Symbol summaries provide per-symbol
profile data. In the following example, we're getting an image summary for the whole
system:
</para>
<screen>
$ opreport --long-filenames
CPU: PIII, speed 863.195 MHz (estimated)
Counted CPU_CLK_UNHALTED events (clocks processor is not halted) with a unit mask of 0x00 (No unit mask) count 23150
905898 59.7415 /usr/lib/gcc-lib/i386-redhat-linux/3.2/cc1plus
214320 14.1338 /boot/2.6.0/vmlinux
103450 6.8222 /lib/i686/libc-2.3.2.so
60160 3.9674 /usr/local/bin/madplay
31769 2.0951 /usr/local/oprofile-pp/bin/oprofiled
26550 1.7509 /usr/lib/libartsflow.so.1.0.0
23906 1.5765 /usr/bin/as
18770 1.2378 /oprofile
15528 1.0240 /usr/lib/qt-3.0.5/lib/libqt-mt.so.3.0.5
11979 0.7900 /usr/X11R6/bin/XFree86
11328 0.7471 /bin/bash
...
</screen>
<para>
If we had specified <option>--symbols</option> in the previous command, we would have
gotten a symbol summary of all the images across the entire system. We can restrict this to only
part of the system profile; for example,
below is a symbol summary of the OProfile daemon. Note that as we used
<command>opcontrol --separate=kernel</command>, symbols from images that <command>oprofiled</command>
has used are also shown.
</para>
<screen>
$ opreport -l `which oprofiled` 2>/dev/null | more
CPU: PIII, speed 863.195 MHz (estimated)
Counted CPU_CLK_UNHALTED events (clocks processor is not halted) with a unit mask of 0x00 (No unit mask) count 23150
vma samples % image name symbol name
0804be10 14971 28.1993 oprofiled odb_insert
0804afdc 7144 13.4564 oprofiled pop_buffer_value
c01daea0 6113 11.5144 vmlinux __copy_to_user_ll
0804b060 2816 5.3042 oprofiled opd_put_sample
0804b4a0 2147 4.0441 oprofiled opd_process_samples
0804acf4 1855 3.4941 oprofiled opd_put_image_sample
0804ad84 1766 3.3264 oprofiled opd_find_image
0804a5ec 1084 2.0418 oprofiled opd_find_module
0804ba5c 741 1.3957 oprofiled odb_hash_add_node
...
</screen>
<para>
These are the two basic ways you are most likely to use regularly, but <command>opreport</command>
can do a lot more than that. For more details, see <xref linkend="opreport-details" />.
</para>
</sect1> <!-- opreport -->
<sect1 id="opannotate">
<title>Outputting annotated source</title>
<para>
The <command>opannotate</command> utility generates annotated source files or assembly listings, optionally
mixed with source.
If you want to see the source file, the profiled application needs to have debug information, and the source
must be available through this debug information. For GCC, you must use the <option>-g</option> option
when you are compiling.
If the binary doesn't contain sufficient debug information, you can still
use <command>opannotate <option>--assembly</option></command> to get annotated assembly.
</para>
<para>
Note that for the reason explained in <xref linkend="hardware-counters" /> the results can be
inaccurate. The debug information itself can add other problems; for example, the line number for a symbol can be
incorrect. Assembly instructions can be re-ordered and moved by the compiler, and this can lead to
crediting source lines with samples not really "owned" by this line. Also see
<xref linkend="interpreting" />.
</para>
<para>
You can output the annotation to one single file, containing all the source found using the
<option>--source</option>. You can use this in conjunction with <option>--assembly</option>
to get combined source/assembly output.
</para>
<para>
You can also output a directory of annotated source files that maintains the structure of
the original sources. Each line in the annotated source is prepended with the samples
for that line. Additionally, each symbol is annotated giving details for the symbol
as a whole. An example:
</para>
<screen>
$ opannotate --source --output-dir=annotated /usr/local/oprofile-pp/bin/oprofiled
$ ls annotated/home/moz/src/oprofile-pp/daemon/
opd_cookie.h opd_image.c opd_kernel.c opd_sample_files.c oprofiled.c
</screen>
<para>
Line numbers are maintained in the source files, but each file has
a footer appended describing the profiling details. The actual annotation
looks something like this :
</para>
<screen>
...
:static uint64_t pop_buffer_value(struct transient * trans)
11510 1.9661 :{ /* pop_buffer_value total: 89901 15.3566 */
: uint64_t val;
:
10227 1.7469 : if (!trans->remaining) {
: fprintf(stderr, "BUG: popping empty buffer !\n");
: exit(EXIT_FAILURE);
: }
:
: val = get_buffer_value(trans->buffer, 0);
2281 0.3896 : trans->remaining--;
2296 0.3922 : trans->buffer += kernel_pointer_size;
: return val;
10454 1.7857 :}
...
</screen>
<para>
The first number on each line is the number of samples, whilst the second is
the relative percentage of total samples.
There are a number of options for specifying the output; for more details,
see <xref linkend="opannotate-details" />.
</para>
<sect2 id="opannotate-finding-source">
<title>Locating source files</title>
<para>
Of course, <command>opannotate</command> needs to be able to locate the source files
for the binary image(s) in order to produce output. Some binary images have debug
information where the given source file paths are relative, not absolute. You can
specify search paths to look for these files (similar to <command>gdb</command>'s
<option>dir</option> command) with the <option>--search-dirs</option> option.
</para>
<para>
Sometimes you may have a binary image which gives absolute paths for the source files,
but you have the actual sources elsewhere (commonly, you've installed an SRPM for
a binary on your system and you want annotation from an existing profile). You can
use the <option>--base-dirs</option> option to redirect OProfile to look somewhere
else for source files. For example, imagine we have a binary generated from a source
file that is given in the debug information as <filename>/tmp/build/libfoo/foo.c</filename>,
and you have the source tree matching that binary installed in <filename>/home/user/libfoo/</filename>.
You can redirect OProfile to find <filename>foo.c</filename> correctly like this :
</para>
<screen>
$ opannotate --source --base-dirs=/tmp/build/libfoo/ --search-dirs=/home/user/libfoo/ --output-dir=annotated/ /lib/libfoo.so
</screen>
<para>
You can specify multiple (comma-separated) paths to both options.
</para>
</sect2>
</sect1> <!-- opannotate -->
<sect1 id="opgprof">
<title><command>gprof</command>-compatible output</title>
<para>
If you're familiar with the output produced by <command>GNU gprof</command>,
you may find <command>opgprof</command> useful. It takes a single binary
as an argument, and produces a <filename>gmon.out</filename> file for use
with <command>gprof -p</command>. Note that only a flat profile is included;
OProfile cannot produce call graphs. For example:
</para>
<screen>
$ opgprof `which oprofiled` # generates gmon.out file
$ gprof -p `which oprofiled` | head
Flat profile:
Each sample counts as 1 samples.
% cumulative self self total
time samples samples calls T1/call T1/call name
33.13 206237.00 206237.00 odb_insert
22.67 347386.00 141149.00 pop_buffer_value
9.56 406881.00 59495.00 opd_put_sample
7.34 452599.00 45718.00 opd_find_image
7.19 497327.00 44728.00 opd_process_samples
</screen>
<para>
A few options to <command>opgprof</command> are available, see
<xref linkend="opgprof-details" />.
</para>
</sect1> <!-- opgprof -->
<sect1 id="profile-spec">
<title>Profile specifications</title>
<para>
All of the analysis tools take a <emphasis>profile specification</emphasis>.
This is a set of definitions that describe which actual profiles should be
examined. The simplest profile specification is empty: this will match all
the available profile files for the current session (this is what happens
when you do <command>opreport</command>).
</para>
<para>
Specification parameters are of the form <option>name:value[,value]</option>.
For example, if I wanted to get a combined symbol summary for
<filename>/bin/myprog</filename> and <filename>/bin/myprog2</filename>,
I could do <command>opreport -l image:/bin/myprog,/bin/myprog2</command>.
As a special case, you don't actually need to specify the <option>image:</option>
part here: anything left on the command line is assumed to be an
<option>image:</option> name. Similarly, if no <option>session:</option>
is specified, then <option>session:current</option> is assumed ("current"
is a special name of the current / last profiling session).
</para>
<para>
In addition to the comma-separated list shown above, some of the
specification parameters can take <command>glob</command>-style
values. For example, if I want to see image summaries for all
binaries profiled in <filename>/usr/bin/</filename>, I could do
<command>opreport image:/usr/bin/\*</command>. Note the necessity
to escape the special character from the shell.
</para>
<sect2 id="profile-spec-examples">
<title>Examples</title>
<para>
Image summaries for all profiles with <constant>DATA_MEM_REFS</constant>
samples in the saved session called "stresstest" :
</para>
<screen>
# opreport session:stresstest event:DATA_MEM_REFS
</screen>
<para>
Symbol summary for the application called "test_sym53c8xx,9xx". Note the
escaping is necessary as <option>image:</option> takes a comma-separated list.
</para>
<screen>
# opreport -l ./test/test_sym53c8xx\,9xx
</screen>
<para>
Get a symbol summary if you have the actual profile file and binary
(perhaps somebody has sent you them via e-mail). These parameters
cannot be used in combination with any others as the default searches
are not performed.
</para>
<screen>
# opreport -l binary:./mybinary sample-file:./CPU_CLK_UNHALTED.231500.0.all.all.all
</screen>
<para>
Image summaries for all binaries in the <filename>test</filename> directory,
excepting <filename>boring-test</filename> :
</para>
<screen>
# opreport image:./test/\* image-exclude:./test/boring-test
</screen>
</sect2> <!-- profile spec examples -->
<sect2 id="profile-spec-details">
<title>Profile specification parameters</title>
<variablelist>
<varlistentry>
<term><option>session:</option><emphasis>sessionlist</emphasis></term>
<listitem><para>
A comma-separated list of session names to resolve in. Absence of this
tag, unlike all others, means "the current session", equivalent to
specifying "session:current".
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>session-exclude:</option><emphasis>sessionlist</emphasis></term>
<listitem><para>
A comma-separated list of sessions to exclude.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>image:</option><emphasis>imagelist</emphasis></term>
<listitem><para>
A comma-separated list of image names to resolve. Each entry may be relative
path, <command>glob</command>-style name, or full path, e.g.</para>
<screen>opreport 'image:/usr/bin/oprofiled,*op*,./opreport'</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><option>image-exclude:</option><emphasis>imagelist</emphasis></term>
<listitem><para>
Same as <option>image:</option>, but the matching images are excluded.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>lib-image:</option><emphasis>imagelist</emphasis></term>
<listitem><para>
Same as <option>image:</option>, but only for images that are for
a particular primary binary image (namely, an application). This only
makes sense to use if you're using <option>--separate</option>.
This includes kernel modules and the kernel when using
<option>--separate=kernel</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>lib-image-exclude:</option><emphasis>imagelist</emphasis></term>
<listitem><para>
Same as <option>lib-image:</option>, but the matching images
are excluded.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>event:</option><emphasis>eventlist</emphasis></term>
<listitem><para>
The symbolic event name to match on, e.g. <option>event:DATA_MEM_REFS</option>.
You can pass a list of events for side-by-side comparison with <command>opreport</command>.
When using the timer interrupt, the event is always "TIMER".
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>count:</option><emphasis>eventcountlist</emphasis></term>
<listitem><para>
The event count to match on, e.g. <option>event:DATA_MEM_REFS count:30000</option>.
Note that this value refers the setting used for <command>opcontrol</command>
only, and has nothing to do with the sample counts in the profile data
itself.
You can pass a list of events for side-by-side comparison with <command>opreport</command>.
When using the timer interrupt, the count is always 0 (indicating it cannot be set).
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>unit-mask:</option><emphasis>masklist</emphasis></term>
<listitem><para>
The unit mask value of the event to match on, e.g. <option>unit-mask:1</option>.
You can pass a list of events for side-by-side comparison with <command>opreport</command>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>binary:</option><emphasis>file</emphasis></term>
<listitem><para>
Give results only for the given file. This can only be used with
<option>sample-file:</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>sample-file:</option><emphasis>file</emphasis></term>
<listitem><para>
Give results only for the given sample file. This can only be used with
<option>binary:</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>cpu:</option><emphasis>cpulist</emphasis></term>
<listitem><para>
Only consider profiles for the given numbered CPU (starting from zero).
This is only useful when using CPU profile separation.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>tgid:</option><emphasis>pidlist</emphasis></term>
<listitem><para>
Only consider profiles for the given task groups. Unless some program
is using threads, the task group ID of a process is the same
as its process ID. This option corresponds to the POSIX
notion of a thread group.
This is only useful when using per-process profile separation.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>tid:</option><emphasis>tidlist</emphasis></term>
<listitem><para>
Only consider profiles for the given threads. When using
recent thread libraries, all threads in a process share the
same task group ID, but have different thread IDs. You can
use this option in combination with <option>tgid:</option> to
restrict the results to particular threads within a process.
This is only useful when using per-process profile separation.
</para></listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
<title>Locating and managing binary images</title>
<para>
Each session's sample files can be found in the <filename>/var/lib/oprofile/samples/</filename> directory.
These are used, along with the binary image files, to produce human-readable data.
In some circumstances (kernel modules in an initrd, or modules on 2.6 kernels), OProfile
will not be able to find the binary images. All the tools have an <option>--image-path</option>
to which you can pass a comma-separated list of alternate paths to search. For example,
I can let OProfile find my 2.6 modules by using <command>--image-path /lib/modules/2.6.0/kernel/</command>.
It is your responsibility to ensure that the correct images are found when using this
option.
</para>
<para>
Note that if a binary image changes after the sample file was created, you won't be able to get useful
symbol-based data out. This situation is detected for you. If you replace a binary, you should
make sure to save the old binary if you need to do comparative profiles.
</para>
</sect2>
<sect2 id="no-results">
<title>What to do when you don't get any results</title>
<para>
When attempting to get output, you may see the error :
</para>
<screen>
error: no sample files found: profile specification too strict ?
</screen>
<para>
What this is saying is that the profile specification you passed in,
when matched against the available sample files, resulted in no matches.
There are a number of reasons this might happen:
</para>
<variablelist>
<varlistentry><term>spelling</term><listitem><para>
You specified a binary name, but spelt it wrongly. Check your spelling !
</para></listitem></varlistentry>
<varlistentry><term>profiler wasn't running</term><listitem><para>
Make very sure that OProfile was actually up and running when you ran
the binary.
</para></listitem></varlistentry>
<varlistentry><term>binary didn't run long enough</term><listitem><para>
Remember OProfile is a statistical profiler - you're not guaranteed to
get samples for short-running programs. You can help this by using a
lower count for the performance counter, so there are a lot more samples
taken per second.
</para></listitem></varlistentry>
<varlistentry><term>binary spent most of its time in libraries</term><listitem><para>
Similarly, if the binary spends little time in the main binary image
itself, with most of it spent in shared libraries it uses, you might
not see any samples for the binary image itself. You can check this
by using <command>opcontrol --separate=library</command> before the
profiling session, so <command>opreport</command> and friends show
the library profiles on a per-application basis.
</para></listitem></varlistentry>
<varlistentry><term>specification was really too strict</term><listitem><para>
For example, you specified something like <option>tgid:3433</option>,
but no task with that group ID ever ran the code.
</para></listitem></varlistentry>
<varlistentry><term>binary didn't generate any events</term><listitem><para>
If you're using a particular event counter, for example counting MMX
operations, the code might simply have not generated any events in the
first place. Verify the code you're profiling does what you expect it
to.
</para></listitem></varlistentry>
<varlistentry><term>you didn't specify kernel module name correctly</term><listitem><para>
If you're using 2.6 kernels, and trying to get reports for a kernel
module, make sure to use the <option>-p</option> option, and specify the
module name <emphasis>with</emphasis> the <filename>.ko</filename>
extension. Check if the module is one loaded from initrd.
</para></listitem></varlistentry>
</variablelist>
</sect2>
</sect1> <!-- profile-spec -->
<sect1 id="opreport-details">
<title>Usage of <command>opreport</command></title>
<sect2 id="opreport-merging">
<title>Merging separate profiles</title>
If you have used one of the <option>--separate=</option> options
whilst profiling, there can be several separate profiles for
a single binary image within a session. Normally the output
will keep these images separated (so, for example, the image summary
output shows library image summaries on a per-application basis,
when using <option>--separate=lib</option>).
Sometimes it can be useful to merge these results back together
before getting results. The <option>--merge</option> option allows
you to do that.
</sect2>
<sect2 id="opreport-comparison">
<title>Side-by-side multiple results</title>
If you have used multiple events when profiling, by default you get
side-by-side results of each event's sample values from <command>opreport</command>.
You can restrict which events to list by appropriate use of the
<option>event:</option> profile specifications, etc.
</sect2>
<sect2 id="opreport-options">
<title>Options for <command>opreport</command></title>
<variablelist>
<varlistentry><term><option>--accumulated / -c</option></term><listitem><para>
Accumulate sample and percentage counts in the symbol list.
</para></listitem></varlistentry>
<varlistentry><term><option>--debug-info / -g</option></term><listitem><para>
Show source file and line for each symbol.
</para></listitem></varlistentry>
<varlistentry><term><option>--demangle none|normal|smart</option></term><listitem><para>
none: no demangling. normal: use default demangler (default) smart: use
pattern-matching to make C++ symbol demangling more readable.
</para></listitem></varlistentry>
<varlistentry><term><option>--details / -d</option></term><listitem><para>
Show per-instruction details for all selected symbols.
</para></listitem></varlistentry>
<varlistentry><term><option>--exclude-dependent / -x</option></term><listitem><para>
Do not include application-specific images for libraries, kernel modules
and the kernel. This option only makes sense if the profile session
used --separate.
</para></listitem></varlistentry>
<varlistentry><term><option>--exclude-symbols / -e [symbols]</option></term><listitem><para>
Exclude all the symbols in the given comma-separated list.
</para></listitem></varlistentry>
<varlistentry><term><option>--global-percent</option></term><listitem><para>
Make all percentages relative to the whole profile.
</para></listitem></varlistentry>
<varlistentry><term><option>--help / -? / --usage</option></term><listitem><para>
Show help message.
</para></listitem></varlistentry>
<varlistentry><term><option>--image-path / -p [paths]</option></term><listitem><para>
Comma-separated list of additional paths to search for binaries.
This is needed to find modules in kernels 2.6 and upwards.
</para></listitem></varlistentry>
<varlistentry><term><option>--include-symbols / -i [symbols]</option></term><listitem><para>
Only include symbols in the given comma-separated list.
</para></listitem></varlistentry>
<varlistentry><term><option>--long-filenames / -l</option></term><listitem><para>
Output full paths instead of basenames.
</para></listitem></varlistentry>
<varlistentry><term><option>--merge / -m [lib,cpu,tid,tgid,unitmask,all]</option></term><listitem><para>
Merge any profiles separated in a --separate session.
</para></listitem></varlistentry>
<varlistentry><term><option>--no-header</option></term><listitem><para>
Don't output a header detailing profiling parameters.
</para></listitem></varlistentry>
<varlistentry><term><option>--output-file / -o [file]</option></term><listitem><para>
Output to the given file instead of stdout.
</para></listitem></varlistentry>
<varlistentry><term><option>--reverse-sort / -r</option></term><listitem><para>
Reverse the sort from the default.
</para></listitem></varlistentry>
<varlistentry><term><option>--show-address / -w</option></term><listitem><para>
Show the VMA address of each symbol (off by default).
</para></listitem></varlistentry>
<varlistentry><term><option>--sort / -s [vma,sample,symbol,debug,image]</option></term><listitem><para>
Sort the list of symbols by, respectively, symbol address,
number of samples, symbol name, debug filename and line number,
binary image filename.
</para></listitem></varlistentry>
<varlistentry><term><option>--symbols / -l</option></term><listitem><para>
List per-symbol information instead of a binary image summary.
</para></listitem></varlistentry>
<varlistentry><term><option>--threshold / -t [percentage]</option></term><listitem><para>
Only output data for symbols that have more than the given percentage
of total samples.
</para></listitem></varlistentry>
<varlistentry><term><option>--verbose / -V</option></term><listitem><para>
Give verbose debugging output.
</para></listitem></varlistentry>
<varlistentry><term><option>--version / -v</option></term><listitem><para>
Show version.
</para></listitem></varlistentry>
</variablelist>
</sect2>
</sect1> <!-- opreport-details -->
<sect1 id="opannotate-details">
<title>Usage of <command>opannotate</command></title>
<variablelist>
<varlistentry><term><option>--assembly / -a</option></term><listitem><para>
Output annotated assembly. If this is combined with --source, then mixed
source / assembly annotations are output.
</para></listitem></varlistentry>
<varlistentry><term><option>--demangle none|normal|smart</option></term><listitem><para>
none: no demangling. normal: use default demangler (default) smart: use
pattern-matching to make C++ symbol demangling more readable.
</para></listitem></varlistentry>
<varlistentry><term><option>--exclude-dependent / -x</option></term><listitem><para>
Do not include application-specific images for libraries, kernel modules
and the kernel. This option only makes sense if the profile session
used --separate.
</para></listitem></varlistentry>
<varlistentry><term><option>--exclude-file [files]</option></term><listitem><para>
Exclude all files in the given comma-separated list of glob patterns.
</para></listitem></varlistentry>
<varlistentry><term><option>--exclude-symbols / -e [symbols]</option></term><listitem><para>
Exclude all the symbols in the given comma-separated list.
</para></listitem></varlistentry>
<varlistentry><term><option>--help / -? / --usage</option></term><listitem><para>
Show help message.
</para></listitem></varlistentry>
<varlistentry><term><option>--image-path / -p [paths]</option></term><listitem><para>
Comma-separated list of additional paths to search for binaries.
This is needed to find modules in kernels 2.6 and upwards.
</para></listitem></varlistentry>
<varlistentry><term><option>--include-file [files]</option></term><listitem><para>
Only include files in the given comma-separated list of glob patterns.
</para></listitem></varlistentry>
<varlistentry><term><option>--include-symbols / -i [symbols]</option></term><listitem><para>
Only include symbols in the given comma-separated list.
</para></listitem></varlistentry>
<varlistentry><term><option>--objdump-params [params]</option></term><listitem><para>
Pass the given parameters as extra values when calling objdump.
</para></listitem></varlistentry>
<varlistentry><term><option>--output-dir / -o [dir]</option></term><listitem><para>
Output directory. This makes opannotate output one annotated file for each
source file.
</para></listitem></varlistentry>
<varlistentry><term><option>--search-dirs / -d [paths]</option></term><listitem><para>
Comma-separated list of paths to search for source files. This is useful to find
source files when the debug information only contains relative paths.
</para></listitem></varlistentry>
<varlistentry><term><option>--base-dirs / -b [paths]/</option></term><listitem><para>
Comma-separated list of path prefixes. This can be used to point OProfile to a
different location for source files when the debug information specifies an
absolute path on your system for the source that does not exist. The prefix
is stripped from the debug source file paths, then searched in the search dirs
specified by <option>--search-dirs</option>.
</para></listitem></varlistentry>
<varlistentry><term><option>--source / -s</option></term><listitem><para>
Output annotated source. This requires debugging information to be available
for the binaries.
</para></listitem></varlistentry>
<varlistentry><term><option>--threshold / -t [percentage]</option></term><listitem><para>
Only output data for symbols that have more than the given percentage
of total samples.
</para></listitem></varlistentry>
<varlistentry><term><option>--verbose / -V</option></term><listitem><para>
Give verbose debugging output.
</para></listitem></varlistentry>
<varlistentry><term><option>--version / -v</option></term><listitem><para>
Show version.
</para></listitem></varlistentry>
</variablelist>
</sect1> <!-- opannotate-details -->
<sect1 id="opgprof-details">
<title>Usage of <command>opgprof</command></title>
<variablelist>
<varlistentry><term><option>--help / -? / --usage</option></term><listitem><para>
Show help message.
</para></listitem></varlistentry>
<varlistentry><term><option>--version / -v</option></term><listitem><para>
Show version.
</para></listitem></varlistentry>
<varlistentry><term><option>--verbose / -V</option></term><listitem><para>
Give verbose debugging output.
</para></listitem></varlistentry>
<varlistentry><term><option>--image-path / -p [paths]</option></term><listitem><para>
Comma-separated list of additional paths to search for binaries.
This is needed to find modules in kernels 2.6 and upwards.
</para></listitem></varlistentry>
<varlistentry><term><option>--threshold / -t [percentage]</option></term><listitem><para>
Only output data for symbols that have more than the given percentage
of total samples.
</para></listitem></varlistentry>
<varlistentry><term><option>--output-filename / -o [file]</option></term><listitem><para>
Output to the given file instead of the default, gmon.out
</para></listitem></varlistentry>
</variablelist>
</sect1> <!-- opgprof-details -->
</chapter>
<chapter id="interpreting">
<title>Interpreting profiling results</title>
<para>
The standard caveats of profiling apply in interpreting the results from OProfile:
profile realistic situations, profile different scenarios, profile
for as long as a time as possible, avoid system-specific artifacts, don't trust
the profile data too much. Also bear in mind the comments on the performance
counters above - you <emphasis>cannot</emphasis> rely on totally accurate
instruction-level profiling. However, for almost all circumstances the data
can be useful. Ideally a utility such as Intel's VTUNE would be available to
allow careful instruction-level analysis; go hassle Intel for this, not me ;)
</para>
<sect1 id="irq-latency">
<title>Profiling interrupt latency</title>
<para>
This is an example of how the latency of delivery of profiling interrupts
can impact the reliability of the profiling data. This is pretty much a
worst-case-scenario example: these problems are fairly rare.
</para>
<screen>
double fun(double a, double b, double c)
{
double result = 0;
for (int i = 0 ; i &lt; 10000; ++i) {
result += a;
result *= b;
result /= c;
}
return result;
}
</screen>
<para>
Here the last instruction of the loop is very costly, and you would expect the result
reflecting that - but (cutting the instructions inside the loop):
</para>
<screen>
$ opannotate -a -t 10 ./a.out
88 15.38% : 8048337: fadd %st(3),%st
48 8.391% : 8048339: fmul %st(2),%st
68 11.88% : 804833b: fdiv %st(1),%st
368 64.33% : 804833d: inc %eax
: 804833e: cmp $0x270f,%eax
: 8048343: jle 8048337
</screen>
<para>
The problem comes from the x86 hardware; when the counter overflows the IRQ
is asserted but the hardware has features that can delay the NMI interrupt:
x86 hardware is synchronous (i.e. cannot interrupt during an instruction);
there is also a latency when the IRQ is asserted, and the multiple
execution units and the out-of-order model of modern x86 CPUs also causes
problems. This is the same function, with annotation :
</para>
<screen>
$ opannotate -s -t 10 ./a.out
:double fun(double a, double b, double c)
:{ /* _Z3funddd total: 572 100.0% */
: double result = 0;
368 64.33% : for (int i = 0 ; i &lt; 10000; ++i) {
88 15.38% : result += a;
48 8.391% : result *= b;
68 11.88% : result /= c;
: }
: return result;
:}
</screen>
<para>
The conclusion: don't trust samples coming at the end of a loop,
particularly if the last instruction generated by the compiler is costly. This
case can also occur for branches. Always bear in mind that samples
can be delayed by a few cycles from its real position. That's a hardware
problem and OProfile can do nothing about it.
</para>
</sect1>
<sect1 id="kernel-profiling">
<title>Kernel profiling</title>
<sect2 id="irq-masking">
<title>Interrupt masking</title>
<para>
OProfile uses non-maskable interrupts (NMI) on the P6 generation, Pentium 4,
Athlon and Duron processors. These interrupts can occur even in section of the
Linux where interrupts are disabled, allowing collection of samples in virtually
all executable code. The RTC, timer interrupt mode, and Itanium 2 collection mechanisms
use maskable interrupts. Thus, the RTC and Itanium 2 data collection mechanism have "sample
shadows", or blind spots: regions where no samples will be collected. Typically, the samples
will be attributed to the code immediately after the interrupts are re-enabled.
</para>
</sect2>
<sect2 id="idle">
<title>Idle time</title>
<para>
Your kernel is likely to support halting the processor when a CPU is idle. As
the typical hardware events like <constant>CPU_CLK_UNHALTED</constant> do not
count when the CPU is halted, the kernel profile will not reflect the actual
amount of time spent idle. You can change this behaviour by booting with
the <option>idle=poll</option> option, which uses a different idle routine. This
will appear as <function>poll_idle()</function> in your kernel profile.
</para>
</sect2>
<sect2 id="exiting-tasks">
<title>Exiting tasks</title>
<para>
The internal implementation of the 2.6 OProfile code means that tasks that
within the kernel <function>do_exit()</function> routine cannot be profiled.
</para>
</sect2>
<sect2 id="kernel-modules">
<title>Profiling kernel modules</title>
<para>
OProfile profiles kernel modules by default. However, there are a couple of problems
you may have when trying to get results. First, you may have booted via an initrd;
this means that the actual path for the module binaries cannot be determined automatically.
To get around this, you can use the <option>-p</option> option to the profiling tools
to specify where to look for the kernel modules.
</para>
<para>
In 2.6, the information on where kernel module binaries are located has been removed.
This means OProfile needs guiding with the <option>-p</option> option to find your
modules. Normally, you can just use your standard module top-level directory for this.
Note that due to this problem, OProfile cannot check that the modification times match;
it is your responsibility to make sure you do not modify a binary after a profile
has been created.
</para>
<para>
If you have run <command>insmod</command> or <command>modprobe</command> to insert a module
in a particular directory, it is important that you specify this directory with the
<option>-p</option> option first, so that it over-rides an older module binary that might
exist in other directories you've specified with <option>-p</option>. It is up to you
to make sure that these values are correct: 2.6 kernels simply do not provide enough
information for OProfile to get this information.
</para>
</sect2>
</sect1>
<sect1 id="debug-info">
<title>Inaccuracies in annotated source</title>
<sect2 id="effect-of-optimizations">
<title>Side effects of optimizations</title>
<para>
The compiler can introduce some pitfalls in the annotated source output.
The optimizer can move pieces of code in such manner that two line of codes
are interlaced (instruction scheduling). Also debug info generated by the compiler
can show strange behavior. This is especially true for complex expressions e.g. inside
an if statement:
</para>
<screen>
if (a &amp;&amp; ..
b &amp;&amp; ..
c &amp;&amp;)
</screen>
<para>
here the problem come from the position of line number. The available debug
info does not give enough details for the if condition, so all samples are
accumulated at the position of the right brace of the expression. Using
<command>opannotate <option>-a</option></command> can help to show the real
samples at an assembly level.
</para>
</sect2>
<sect2 id="prologues">
<title>Prologues and epilogues</title>
<para>
The compiler generally needs to generate "glue" code across function calls, dependent
on the particular function call conventions used. Additionally other things
need to happen, like stack pointer adjustment for the local variables; this
code is known as the function prologue. Similar code is needed at function return,
and is known as the function epilogue. This will show up in annotations as
samples at the very start and end of a function, where there is no apparent
executable code in the source.
</para>
</sect2>
<sect2 id="inlined-function">
<title>Inlined functions</title>
<para>
You may see that a function is credited with a certain number of samples, but
the listing does not add up to the correct total. To pick a real example :
</para>
<screen>
:internal_sk_buff_alloc_security(struct sk_buff *skb)
353 2.342% :{ /* internal_sk_buff_alloc_security total: 1882 12.48% */
:
: sk_buff_security_t *sksec;
15 0.0995% : int rc = 0;
:
10 0.06633% : sksec = skb-&gt;lsm_security;
468 3.104% : if (sksec &amp;&amp; sksec-&gt;magic == DSI_MAGIC) {
: goto out;
: }
:
: sksec = (sk_buff_security_t *) get_sk_buff_memory(skb);
3 0.0199% : if (!sksec) {
38 0.2521% : rc = -ENOMEM;
: goto out;
10 0.06633% : }
: memset(sksec, 0, sizeof (sk_buff_security_t));
44 0.2919% : sksec-&gt;magic = DSI_MAGIC;
32 0.2123% : sksec-&gt;skb = skb;
45 0.2985% : sksec-&gt;sid = DSI_SID_NORMAL;
31 0.2056% : skb-&gt;lsm_security = sksec;
:
: out:
:
146 0.9685% : return rc;
:
98 0.6501% :}
</screen>
<para>
Here, the function is credited with 1,882 samples, but the annotations
below do not account for this. This is usually because of inline functions -
the compiler marks such code with debug entries for the inline function
definition, and this is where <command>opannotate</command> annotates
such samples. In the case above, <function>memset</function> is the most
likely candidate for this problem. Examining the mixed source/assembly
output can help identify such results.
</para>
<para>
When running <command>opannotate</command>, you may get a warning
"some functions compiled without debug information may have incorrect source line attributions".
In some rare cases, OProfile is not able to verify that the derived source line
is correct (when some parts of the binary image are compiled without debugging
information). Be wary of results if this warning appears.
</para>
<para>
Furthermore, for some languages the compiler can implicitly generate functions,
such as default copy constructors. Such functions are labelled by the compiler
as having a line number of 0, which means the source annotation can be confusing.
</para>
<!-- FIXME so what *actually* happens to those samples ? ignored ? -->
</sect2>
<sect2 id="wrong-linenr-info">
<title>Inaccuracy in line number information</title>
<para>
Depending on your compiler you can fall into the following problem:
</para>
<screen>
struct big_object { int a[500]; };
int main()
{
big_object a, b;
for (int i = 0 ; i != 1000 * 1000; ++i)
b = a;
return 0;
}
</screen>
<para>
Compiled with <command>gcc</command> 3.0.4 the annotated source is clearly inaccurate:
</para>
<screen>
:int main()
:{ /* main total: 7871 100% */
: big_object a, b;
: for (int i = 0 ; i != 1000 * 1000; ++i)
: b = a;
7871 100% : return 0;
:}
</screen>
<para>
The problem here is distinct from the IRQ latency problem; the debug line number
information is not precise enough; again, looking at output of <command>opannoatate -as</command> can help.
</para>
<screen>
:int main()
:{
: big_object a, b;
: for (int i = 0 ; i != 1000 * 1000; ++i)
: 80484c0: push %ebp
: 80484c1: mov %esp,%ebp
: 80484c3: sub $0xfac,%esp
: 80484c9: push %edi
: 80484ca: push %esi
: 80484cb: push %ebx
: b = a;
: 80484cc: lea 0xfffff060(%ebp),%edx
: 80484d2: lea 0xfffff830(%ebp),%eax
: 80484d8: mov $0xf423f,%ebx
: 80484dd: lea 0x0(%esi),%esi
: return 0;
3 0.03811% : 80484e0: mov %edx,%edi
: 80484e2: mov %eax,%esi
1 0.0127% : 80484e4: cld
8 0.1016% : 80484e5: mov $0x1f4,%ecx
7850 99.73% : 80484ea: repz movsl %ds:(%esi),%es:(%edi)
9 0.1143% : 80484ec: dec %ebx
: 80484ed: jns 80484e0
: 80484ef: xor %eax,%eax
: 80484f1: pop %ebx
: 80484f2: pop %esi
: 80484f3: pop %edi
: 80484f4: leave
: 80484f5: ret
</screen>
<para>
So here it's clear that copying is correctly credited with of all the samples, but the
line number information is misplaced. <command>objdump -dS</command> exposes the
same problem. Note that maintaining accurate debug information for compilers when optimizing is difficult, so this problem is not suprising.
The problem of debug information
accuracy is also dependent on the binutils version used; some BFD library versions
contain a work-around for known problems of <command>gcc</command>, some others do not. This is unfortunate but we must live with that,
since profiling is pointless when you disable optimisation (which would give better debugging entries).
</para>
</sect2>
</sect1>
<sect1 id="symbol-without-debug-info">
<title>Assembly functions</title>
<para>
Often the assembler cannot generate debug information automatically.
This means that you cannot get a source report unless
you manually define the neccessary debug information; read your assembler documentation for how you might
do that. The only
debugging info needed currently by OProfile is the line-number/filename-VMA association. When profiling assembly
without debugging info you can always get report for symbols, and optionally for VMA, through <command>opreport -l</command>
or <command>opreport -d</command>, but this works only for symbol with the right attributes.
For <command>gas</command> you can get this by
</para>
<screen>
.globl foo
.type foo,@function
</screen>
<para>
whilst for <command>nasm</command> you must use
</para>
<screen>
GLOBAL foo:function ; [1]
</screen>
<para>
Note that OProfile does not need the global attribute, only the function attribute.
</para>
</sect1>
<!--
FIXME: I commented this bit out until we've written something ...
improve this ? but look first why this file is special
<sect2 id="small-functions">
<title>Small functions</title>
<para>
Very small functions can show strange behavior. The file in your source
directory of OProfile <filename>$SRC/test-oprofile/understanding/puzzle.c</filename>
show such example
</para>
</sect2>
-->
<sect1 id="hidden-cost">
<title>Other discrepancies</title>
<para>
Another cause of apparent problems is the hidden cost of instructions. A very
common example is two memory reads: one from L1 cache and the other from memory:
the second memory read is likely to have more samples.
There are many other causes of hidden cost of instructions. A non-exhaustive
list: mis-predicted branch, TLB cache miss, partial register stall,
partial register dependencies, memory mismatch stall, re-executed �ops. If you want to write
programs at the assembly level, be sure to take a look at the Intel and
AMD documentation at <ulink url="http://developer.intel.com/">http://developer.intel.com/</ulink>
and <ulink url="http://www.amd.com/products/cpg/athlon/techdocs/">http://www.amd.com/products/cpg/athlon/techdocs/</ulink>.
</para>
</sect1>
</chapter>
<chapter id="ack">
<title>Acknowledgments</title>
<para>
Thanks to (in no particular order) : Arjan van de Ven, Rik van Riel, Juan Quintela, Philippe Elie,
Phillipp Rumpf, Tigran Aivazian, Alex Brown, Alisdair Rawsthorne, Bob Montgomery, Ray Bryant, H.J. Lu,
Jeff Esper, Will Cohen, Graydon Hoare, Cliff Woolley, Alex Tsariounov, Al Stone, Jason Yeh,
Randolph Chung, Anton Blanchard, Richard Henderson, Andries Brouwer, Bryan Rittmeyer,
Richard Reich (rreich@rdrtech.com), Zwane Mwaikambo, Dave Jones, Charles Filtness; and finally Pulp, for "Intro".
</para>
</chapter>
</book>

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks