test

Sun Studio 12：性能分析器

第 6 章 er_print 命令行性能分析工具

本章介绍如何使用 er_print 实用程序进行性能分析。er_print 实用程序列显性能分析器支持的各种显示的 ASCII 版本。除非将信息重定向到某个文件，否则这些信息将写入标准输出。必须为 er_print 实用程序提供由收集器生成的一个或多个实验或实验组的名称作为参数。可以使用 er_print 实用程序显示函数、调用者和被调用者的性能度量；源代码列表和反汇编代码列表；抽样信息；数据空间数据；以及执行统计数据。

本章包含以下主题。

有关收集器所收集的数据的说明，请参见第 2 章，性能数据。

有关如何使用性能分析器以图形格式显示信息的说明，请参见第 4 章，性能分析器工具和联机帮助。

er_print 语法

er_print 实用程序的命令行语法如下：


er_print [ -script script | -command | - | -V ] experiment-list

er_print 实用程序 的选项如下：

-

读取从键盘输入的 er_print 命令。

-script script

从文件 script 读取命令（该文件包含 er_print 命令的列表，每行一个命令）。如果 -script 选项不存在，则 er_print 从终端或从命令行读取命令。

-command [argument]

处理给定的命令。

-V

显示版本信息并退出。

多个选项可以出现在 er_print 命令行上。它们按其出现顺序进行处理。可以按任何顺序混合脚本、连字符和显式命令。未提供任何命令或脚本时的缺省操作是进入交互模式，在该模式下命令是从键盘输入的。要退出交互模式，请键入 quit 或 Ctrl-D。

处理每个命令后，会列显处理时出现的任何错误消息或警告消息。可以使用 procstats 命令列显有关处理的摘要统计数据。

在以下各节中列出了 er_print 实用程序接受的命令。

只要命令是明确的，就可以将其缩写为更短的字符串。通过以反斜杠 \ 结束行的方式可以将一个命令拆分为多行。以 \ 结尾的任何行在解析之前都会将 \ 字符删除，并追加下一行的内容。除可用内存外，对命令可使用的行数并没有限制。

必须将包含嵌入空白的参数用双引号引起来。可以将引号内的文本拆分为多行。

度量列表

许多 er_print 命令都使用度量关键字的列表。列表的语法如下：


metric-keyword-1[:metric-keyword2…]

对于动态度量（它们基于度量的数据），度量关键字包含以下三部分：度量类型字符串、度量可见性字符串和度量名称字符串。这些字符串连接在一起且没有空格，如下所示。


flavorvisibilityname

对于静态度量－它们基于实验中装入对象的静态属性（名称、地址和大小），度量关键字包含度量名称和可选的前置度量可见性字符串，两者连接在一起且没有空格：


[visibility]name

度量 flavor 和度量 visibility 字符串由类型和可见性字符组成。

表 6–1 中列出了允许的度量类型字符。包含多个类型字符的度量关键字可扩展为一系列度量关键字。例如，ie.user 可扩展为 i.user:e.user。

表 6–1 度量类型字符

字符 

说明 

e

显示独占度量值 

i

显示包含度量值 

a

显示归属度量值（仅适用于调用者-被调用者度量） 

d 

显示动态度量值（仅适用于数据派生的度量） 

表 6–2 中列出了允许的度量可见性字符。可见性字符串中可见性字符的顺序无关紧要：它不影响对应度量的显示顺序。例如，i%.user 和 i.%user 都解释为 i.user:i%user。

仅可见性不同的度量始终按标准顺序一起显示。如果仅可见性不同的两个度量关键字由某些其他关键字分隔，则度量按标准顺序出现在两个度量中第一个度量的位置。

表 6–2 度量可见性字符

字符 

说明 

.

将度量显示为时间。适用于计时度量以及度量循环计数的硬件计数器度量。其他度量解释为 "+"。

%

将度量显示为总程序度量的百分比。对于调用者-被调用者列表中的归属度量，将度量显示为所选函数的包含度量的百分比。 

+

将度量显示为绝对值。对于硬件计数器，该值是事件计数。计时度量解释为 "."。

!

不显示任何度量值。不能与其他可见性字符组合使用。 

当类型字符串和可见性字符串都具有多个字符时，首先扩展类型。因此，将 ie.%user 扩展为 i.%user:e.%user，然后将其解释为 i.user:i%user:e.user:e%user。

对于静态度量，句点 (.)、加号 (+) 和百分号 (%) 这三种可见性字符在用于定义排序顺序时是等效的。因此，sort i%user、sort i.user 和 sort i+user 均表示只要包含用户 CPU 时间以任一形式可见，分析器就应该按它排序；而 sort i!user 则表示不管包含用户 CPU 时间是否可见，分析器都应该按它排序。

对于每种度量类型，可以使用叹号 (!) 可见性字符覆盖内置可见性缺省值。

如果同一度量在度量列表中出现多次，则仅处理第一次出现的该度量，而忽略随后出现的该度量。如果指定的度量不在列表中，则将它附加到列表中。

表 6–3 中列出了计时度量、同步延迟度量、内存分配度量、MPI 跟踪度量以及两个常见的硬件计数器度量的可用 er_print 度量名称字符串。对于其他硬件计数器度量，度量名称字符串与计数器名称相同。通过 metric_list 命令，可以获取已装入实验的所有可用度量名称字符串的列表。通过使用不带参数的 collect 命令，可以获取计数器名称的列表。有关硬件计数器的更多信息，请参见硬件计数器溢出分析数据。

表 6–3 度量名称字符串

类别 

字符串 

说明 

计时度量 

user

用户 CPU 时间 
 

wall

挂钟时间 
 

total

总 LWP 时间 
 

system

系统 CPU 时间 
 

wait

CPU 等待时间 
 

ulock

用户锁定时间 
 

text

文本缺页时间 
 

data

数据缺页时间 
 

owait

其他等待时间 

同步延迟度量 

sync

同步等待时间 
 

syncn

同步等待计数 

MPI 跟踪度量 

mpitime

MPI 调用所用的时间 
 

mpisend

MPI 发送操作的数量 
 

mpibytessent

在 MPI 发送操作中发送的字节数 
 

mpireceive

MPI 接收操作的数量 
 

mpibytesrecv

在 MPI 接收操作中接收的字节数 
 

mpiother

对其他 MPI 函数的调用数 

内存分配度量 

alloc

分配的数量 
 

balloc

分配的字节 
 

leak

泄漏的数量 
 

bleak

泄漏的字节 

硬件计数器溢出度量 

cycles

CPU 周期 
 

insts

发出的指令 

线程分析器度量 

raccesses

数据争用访问 
 

deadlocks

死锁 

除了表 6–3 中列出的名称字符串外，还有两个只能在缺省度量列表中使用的名称字符串。这两个名称字符串是 hwc（它与任何硬件计数器名称匹配）和 any（它与任何度量名称字符串匹配）。另请注意，cycles 和 insts 对于 SPARC® 平台和 x86 平台是通用的，但是还存在特定于体系结构的其他类型的名称字符串。要列出所有可用的计数器，请使用不带参数的 collect 命令。

要查看在已装入的实验中可用的度量，请使用 metric_list 命令。

控制函数列表的命令

以下命令控制显示函数信息的方式。

functions

使用当前选定的度量写入函数列表。函数列表包括选定进行函数显示的装入对象中的所有函数，以及使用 object_select 命令隐藏其函数的任何装入对象。

可以使用 limit 命令限制写入的行数（请参见控制输出的命令）。

列显的缺省度量是独占和包含用户 CPU 时间，以秒和总程序度量百分比表示。可以使用 metrics 命令更改当前显示的度量，该命令必须在发出 functions 命令之前发出。也可以在 .er.rc 文件中使用 dmetrics 命令更改缺省值。

对于用 Java 编程语言编写的应用程序，显示的函数信息因视图模式的设置而异，视图模式可设置为用户、专家或计算机。

在所有三种模式下，对于 Java 目标调用的任何 C、C++ 或 Fortran 代码，都以通用的方法报告数据。

metrics metric_spec

指定函数列表度量的选项。字符串 metric_spec 可以是恢复缺省度量选项的关键字 default，也可以是由冒号分隔的一系列度量关键字。以下示例说明一个度量列表。


% metrics i.user:i%user:e.user:e%user

此命令指示 er_print 实用程序显示以下度量：

缺省情况下，所用的度量设置基于从 .er.rc 文件处理的 dmetrics 命令，如设置缺省值的命令中所述。如果 metrics 命令将 metric_spec 显式设置为 default，则根据所记录的数据恢复缺省设置。

重置度量时，会在新列表中设置缺省排序度量。

如果省略 metric_spec，则显示当前的度量设置。

除了设置函数列表的度量外，metrics 命令还将调用者-被调用者的度量以及数据派生输出的度量设为相同的设置。有关详细信息，请参见cmetrics metric_spec和data_metrics metric_spec。

处理 metrics 命令时，将列显一条消息，指明当前的度量选项。对于前面的示例，消息如下。


current: i.user:i%user:e.user:e%user:name

有关度量列表的语法的信息，请参见度量列表。要查看可用度量的列表，请使用 metric_list 命令。

如果 metrics 命令中包含错误，则忽略它并显示一条警告，但先前的设置仍然有效。

sort metric_spec

按 metric_spec 对函数列表进行排序。度量名称中的 visibility 不影响排序顺序。如果在 metric_spec 中指定了多个度量，则使用第一个可见度量。如果指定的度量都不可见，则忽略该命令。可以在 metric_spec 前加上减号 (-) 以指定反向排序。

缺省情况下，度量排序设置基于从 .er.rc 文件处理的 dsort 命令，如设置缺省值的命令中所述。如果 sort 命令将 metric_spec 显式设置为 default，则使用缺省设置。

字符串 metric_spec 为度量列表中所述的度量关键字之一，如以下示例所示。


% sort i.user

此命令指示 er_print 实用程序按包含用户 CPU 时间对函数列表进行排序。如果度量不在已装入的实验中，则列显一条警告并忽略该命令。完成命令时，将列显排序度量。

fsummary

为函数列表中的每个函数写入摘要面板。可以使用 limit 命令限制写入的面板数（请参见控制输出的命令）。

摘要度量面板包括函数或装入对象的名称、地址和大小（对于函数，还包括源文件、目标文件和装入对象的名称），以及选定函数或装入对象的所有记录的度量（包括以值和百分比形式表示的独占和包含度量）。

fsingle function_name [N]

为指定的函数写入摘要面板。当有多个函数具有相同的名称时，需要使用可选参数 N。为具有给定函数名称的第 N 个函数写入摘要度量面板。在命令行上提供命令时，N 是必需的；如果不需要它，则将其忽略。当以交互方式提供不带 N 的命令但又需要 N 时，则会列显具有对应 N 值的函数列表。

有关函数的摘要度量的说明，请参见对 fsummary 命令的描述。

控制调用者-被调用者列表的命令

以下命令控制显示调用者和被调用者信息的方式。

callers-callees

按函数排序度量 (sort) 指定的顺序，列显每个函数的调用者-被调用者面板。

在每个调用者-被调用者报告中，调用者和被调用者按调用者-被调用者排序度量 (csort) 进行排序。可以使用 limit 命令限制写入的面板数（请参见控制输出的命令）。选定的（中央）函数以星号标记，如以下示例所示。


Attr.     Excl.     Incl.      Name
User CPU  User CPU  User CPU
 sec.      sec.       sec.
4.440     0.        42.910     commandline
0.        0.         4.440    *gpf
4.080     0.         4.080     gpf_b
0.360     0.         0.360     gpf_a

在此示例中，gpf 是选定的函数；它由 commandline 调用，而它调用 gpf_a 和 gpf_b。

cmetrics metric_spec

指定调用者-被调用者度量的选项。缺省情况下，只要更改了函数列表度量，就会将调用者-被调用者度量设置为与函数列表度量匹配。如果省略 metric_spec，则显示当前的调用者-被调用者度量设置。

字符串 metric_spec 为度量列表中所述的度量关键字之一，如以下示例所示。


% cmetrics i.%user:a.%user

此命令指示 er_print 显示以下度量。

完成 cmetrics 命令时，将列显一条消息，指明当前的度量选项。对于前面的示例，消息如下。


current: i.%user:a.%user:name

缺省情况下，只要更改了函数列表度量，就会将调用者-被调用者度量设置为与函数列表度量匹配。

调用者-被调用者归属度量被插入到对应的独占度量和包含度量前面，visibility 对应于这两个度量的 visibility 设置的逻辑“或”。将静态度量设置复制到调用者-被调用者度量。如果 metric-name 不在列表中，则将它附加到列表中。

可以使用 cmetric_list 命令获取已装入实验的所有可用 metric-name 值的列表。

如果 cmetrics 命令中包含错误，则忽略它并显示一条警告，但先前的设置仍然有效。

csingle function_name [N]

为指定的函数写入调用者-被调用者面板。当有多个函数具有相同的名称时，需要使用可选参数 N。为具有给定函数名称的第 N 个函数写入调用者-被调用者面板。在命令行上提供命令时，N 是必需的；如果不需要它，则将其忽略。当以交互方式提供不带 N 的命令但又需要 N 时，则会列显具有对应 N 值的函数列表。

csort metric_spec

按指定的度量对调用者-被调用者显示进行排序。字符串 metric_spec 为度量列表中所述的度量关键字之一，如以下示例所示。


% csort a.user

如果省略 metric-spec，则显示当前的调用者-被调用者排序度量。

csort 度量必须是归属度量或静态度量。如果指定了多个度量，则按匹配的第一个可见度量进行排序。

只要设置了度量（显式设置或缺省设置），就会基于函数度量设置调用者-被调用者排序度量，如下所示：

此命令指示 er_print 实用程序按归属用户 CPU 时间对调用者-被调用者显示进行排序。命令完成时，将列显排序度量。

控制泄漏和分配列表的命令

本节介绍与内存分配和解除分配相关的命令。

leaks

显示由通用调用栈聚集的内存泄漏列表。每个条目显示了总泄漏数和给定调用栈的总泄漏字节数。该列表按泄漏的字节数进行排序。

allocs

显示由通用调用栈聚集的内存分配列表。每个条目显示了分配数和给定调用栈的总分配字节数。该列表按分配的字节数进行排序。

控制源代码和反汇编代码列表的命令

以下命令控制显示带注释的源代码和反汇编代码的方式。

pcs

写入程序计数器 (program counter, PC) 及其度量的列表（按当前排序度量排序）。该列表包括为使用 object_select 命令隐藏其函数的每个装入对象显示聚集度量的行。

psummary

按当前排序度量指定的顺序，为 PC 列表中的每个 PC 写入摘要度量面板。

lines

写入源代码行及其度量的列表（按当前排序度量排序）。该列表包括为没有行号信息或其源文件未知的每个函数显示聚集度量的行，以及为使用 object_select 命令隐藏其函数的每个装入对象显示聚集度量的行。

lsummary

按当前排序度量指定的顺序，为行列表中的每个行写入摘要度量面板。

source { filename | function_name } [ N]

为指定文件或包含指定函数的文件写出带注释的源代码。在任一种情况下，该文件都必须位于您所指定的路径中的目录下。如果使用 GNU Fortran 编译器编译了源代码，则函数名称出现在源代码中时，必须在其后添加两个下划线字符。

仅当文件或函数的名称不明确时，才使用可选参数 N（正整数）；在这种情况下，使用第 N 个可能的选项。如果提供不带数字说明符的不明确名称，则 er_print 实用程序将列显可能的目标文件名称的列表；如果提供的名称是函数，则将函数名称附加到目标文件名称，还将列显表示该目标文件的 N 值的数字。

也可以将函数名称指定为 function”file”，其中 file 用于指定函数的替代源上下文。紧邻第一个指令之后，将添加函数的索引行。索引行显示为尖括号内的文本，其格式如下：

<Function: f_name>

任何函数的缺省源上下文都被定义为该函数的第一条指令所归属的源文件。它通常是经过编译而生成包含该函数的目标模块的源文件。替代源上下文由包含归属于该函数的指令的其他文件组成。此类上下文包括来自头文件的指令和来自内联到指定函数中的函数的指令。如果存在任何替代源上下文，则在缺省源上下文的开头包括扩展索引行的列表以指示替代源上下文所在的位置，格式如下：

<Function: f, instructions from source file src.h>

注 –

如果在命令行上调用 er_print 实用程序时使用了 -source 参数，则必须在 file 引号前加上反斜杠转义符。换句话说，函数名称的格式为 function\"file\"。当 er_print 实用程序处于交互模式时，反斜杠不是必需的，也不应使用它。

通常，在使用缺省源上下文时，会显示该文件中所有函数的度量。如果显式引用该文件，则仅显示指定函数的度量。

disasm { filename | function_name } [ N]

为指定文件或包含指定函数的文件写出带注释的反汇编代码。该文件必须位于您所指定的路径中的目录下。

可选参数 N 与 source 命令的可选参数的使用方法相同。

scc com_spec

指定在带注释的源代码列表中显示的编译器注释的类。类列表是类的冒号分隔列表，包含零个或多个以下消息类。

表 6–4 编译器注释消息类

类 

含义 

b[asic]

显示基本级别的消息。 

v[ersion]

显示版本消息，包括源文件名称和上次修改日期、编译器组件的版本、编译日期和选项。 

pa[rallel]

显示有关并行化的消息。 

q[uery]

显示有关影响代码优化的代码问题。 

l[oop]

显示有关循环优化和转换的消息。 

pi[pe]

显示有关循环的流水线作业的消息。 

i[nline]

显示有关函数内联的消息。 

m[emops]

显示有关内存操作（如装入、存储、预取）的消息。 

f[e]

显示前端消息。 

all

显示所有消息。 

none

不显示任何消息。 

类 all 和 none 不能与其他类一起使用。

如果未提供 scc 命令，则显示的缺省类为 basic。如果提供了 scc 命令，但 class-list 为空，则关闭编译器注释。scc 命令通常仅在 .er.rc 文件中使用。

sthresh value

指定带注释的源代码中突出显示度量的阈值百分比。对于文件中的任何源代码行，如果任何度量的值等于或大于该度量最大值的 value %，则在该度量所在行的开头插入 ##。

dcc com_spec

指定在带注释的反汇编代码列表中显示的编译器注释的类。类列表是类的冒号分隔列表。可用类的列表与表 6–4 中所示的带注释的源代码列表的类列表相同。可以在类列表中添加以下选项。

表 6–5 dcc 命令的附加选项

选项 

含义 

h[ex]

显示指令的十六进制值。 

noh[ex]

不显示指令的十六进制值。 

s[rc]

在带注释的反汇编代码列表中交错显示源代码列表。 

nos[rc]

不在带注释的反汇编代码列表中交错显示源代码列表。 

as[rc]

在带注释的反汇编代码列表中交错显示带注释的源代码。 

dthresh value

指定带注释的反汇编代码中突出显示度量的阈值百分比。对于文件中的任何指令行，如果任何度量的值等于或大于该度量最大值的 value %，则在该度量所在行的开头插入 ##。

cc com_spec

指定在带注释的源代码和反汇编代码列表中显示的编译器注释的类。类列表是类的冒号分隔列表。可用类的列表与表 6–4 中所示的带注释的源代码列表的类列表相同。

setpath path_list

设置用于查找源文件、目标文件等文件的路径。path_list 是目录的冒号分隔列表。如果任何目录中包含冒号字符，请用反斜杠将它转义。特殊目录名称 $expts 引用当前实验集（按装入实验的顺序）；可以将其缩写为单个 $ 字符。

缺省设置为：$expts:.。如果在搜索当前路径设置时未找到文件，则使用编译时的全路径名。

不带参数的 setpath 列显当前路径。

addpath path_list

将 path_list 附加到当前 setpath 设置。

pathmap old-prefix new-prefix

如果使用由 addpath 或 setpath 设置的 path_list 找不到文件，则可以使用 pathmap 命令指定一个或多个路径重映射。在以 old-prefix 所指定的前缀开头的源文件、目标文件或共享对象的任何路径名中，旧的前缀将由 new-prefix 所指定的新前缀替代。然后，使用所得到的路径查找文件。可采用多个 pathmap 命令，并逐一尝试，直到找到文件为止。

控制数据空间列表的命令

数据空间命令仅适用于在其中指定了主动回溯的硬件计数器实验，以及使用 -xhwcprof 选项（该选项在 SPARC 平台上可用）编译的文件中的对象。有关详细信息，请参见《Sun Studio 12：Fortran 用户指南》、《Sun Studio 12：C 用户指南》或《Sun Studio 12：C++ 用户指南》。

data_objects

写入数据对象及其度量的列表。

data_single name [N]

写入指定数据对象的摘要度量面板。在对象名称不明确的情况下，需要使用可选参数 N。当指令在命令行上时，N 是必需的；如果不需要它，则将其忽略。

data_layout

为具有数据派生度量数据的所有程序数据对象写入带注释的数据对象布局，按整个结构的当前数据排序度量值排序。每个聚集数据对象会显示归属于该对象的总度量，后跟按偏移顺序显示的所有元素，每个元素具有自己的度量和相对于 32 字节块的大小和位置指示符。

data_metrics metric_spec

设置数据派生的度量。metric_spec 是在度量列表中定义的。

缺省情况下，只要更改了函数列表度量，就会将数据派生的度量设置为与函数列表度量匹配。将对应于任何具有数据派生类型的可见独占度量或包含度量的数据派生度量设置为 visibility 对应于这两个度量的 visibility 设置的逻辑“或”。

将静态度量设置复制到数据派生的度量。如果度量名称不在列表中，则将度量名称附加到列表中。

如果省略 metric_spec，则显示当前的数据派生度量设置。

可以使用 data_metric_list 命令获取已装入实验的所有可用 metric-name 值的列表。

如果 metric_spec 存在任何错误，则忽略它，而数据派生度量保持不变。

data_sort

设置数据对象的排序度量。动态度量需要前缀 d，而静态度量可以省略它。data_sort 度量必须是数据派生的度量或静态度量。

如果指定了多个度量，则按匹配的第一个可见度量进行排序。只要设置了度量（显式设置或缺省设置），就会基于函数度量设置数据派生排序度量：

控制内存对象列表的命令

内存对象命令仅适用于在其中指定了主动回溯的硬件计数器实验，以及使用 -xhwcprof 选项（该选项在 SPARC 平台上可用）编译的文件中的对象。有关详细信息，请参见《Sun Studio 12：Fortran 用户指南》、《Sun Studio 12：C 用户指南》或《Sun Studio 12：C++ 用户指南》。

内存对象是内存子系统中的组件，如高速缓存行、页面和内存区。对象是通过从所记录的虚拟地址或物理地址计算的索引确定的。为虚拟页面和物理页面预定义了内存对象，其大小为 8KB、64KB、512KB 和 4 MB。可以使用 mobj_define 命令定义其他内存对象。

以下命令控制内存对象列表。

memobj mobj_type

使用当前度量写入给定类型的内存对象的列表。所用度量和排序方式与数据空间列表相同。还可以将名称 mobj_type 直接用作命令。

mobj_list

写入已知类型的内存对象的列表，用法与 memobj 命令中的 mobj_type 相同。

mobj_define mobj_type index_exp

通过将 VA/PA 映射到由 index_exp 提供的对象，定义新的内存对象类型。表达式的语法在表达式语法中介绍。

不应先定义 mobj_type。其名称必须完全由字母数字字符或 "_" 字符组成，且以字母字符开头。

index_exp 必须在语法上是正确的。如果它在语法上不正确，则将返回错误并忽略定义。

<Unknown> 内存对象的索引是 -1，而且用于定义新内存对象的表达式应该支持识别 <Unknown>。例如，对于基于 VADDR 的对象，表达式应该采用以下格式：

VADDR>255?expression :-1

而对于基于 PADDR 的对象，表达式应该采用以下格式：

PADDR>0?expression:-1

控制索引对象列表的命令

索引对象命令适用于所有实验。索引对象列表是可以从所记录的数据计算其索引的对象的列表。为线程、Cpu、抽样和秒预定义了索引对象。可以使用 indxobj_define 命令定义其他索引对象。

以下命令控制索引对象列表。

indxobj indxobj_type

写入与给定类型匹配的索引对象及其度量的列表。索引对象的度量和排序方式与函数列表相同，只不过仅包含独占度量。也可以将名称 indxobj_type 直接用作命令。

indxobj_list

写入已知类型的索引对象的列表，用法与 indxobj 命令中的 indxobj_type 相同。

indxobj_define indxobj_type index_exp

通过将包映射到由 index_exp 提供的对象，定义新的索引对象类型。表达式的语法在表达式语法中介绍。

不应先定义 indxobj_type。其名称不区分大小写，必须完全由字母数字字符或 "_" 字符组成，且以字母字符开头。

index_exp 必须在语法上是正确的，否则将返回错误并忽略定义。如果 index_exp 包含任何空格，则必须用双引号 (") 将其引起来。

<Unknown> 索引对象的索引是 -1，而且用于定义新索引对象的表达式应该支持识别 <Unknown>。

例如，对于基于虚拟或物理 PC 的索引对象，表达式应该采用以下格式：


VIRTPC>0?VIRTPC:-1

indxobj_metrics metric_spec

指定索引对象的度量选项。metric_spec 只能包含独占度量和静态度量，因为索引对象是不分层的。

有关度量列表的语法的信息，请参见度量列表。要查看可用度量的列表，请使用 metric_list 命令。

indxobj_sort metric_spec

按指定的度量对索引对象列表进行排序。indxobj_sort 度量必须是独占度量或静态度量。如果指定了多个度量，则按匹配的第一个可见度量进行排序。

支持线程分析器的命令

以下命令支持线程分析器。有关捕获和显示的数据的更多信息，请参见《Sun Studio 12：线程分析器用户指南》。

races

写入实验中所有数据争用的列表。数据争用报告只能从具有数据争用检测数据的实验获得。

rdetail race_id

写入给定 race_id 的详细信息。如果 race_id 设置为 all，则显示所有数据争用的详细信息。数据争用报告只能从具有数据争用检测数据的实验获得。

deadlocks

写入实验中检测到的所有实际死锁和潜在死锁的列表。死锁报告只能从具有死锁检测数据的实验获得。

ddetail deadlock_id

写入给定 deadlock_id 的详细信息。如果 deadlock_id 设置为 all，则显示所有死锁的详细信息。死锁报告只能从具有死锁检测数据的实验获得。

列出实验、抽样、线程和 LWP 的命令

本节介绍列出实验、抽样、线程和 LWP 的命令。

experiment_list

显示装入的实验及其 ID 号的完整列表。列出的每个实验都有一个索引（在选择抽样、线程或 LWP 时使用）和一个 PID（可在高级过滤时使用）。

以下示例显示一个实验列表。


(er_print) experiment_list
ID Experiment
== ==========
1 test.1.er
2 test.6.er

sample_list

显示当前选定的要进行分析的抽样的列表。

以下示例显示一个抽样列表。


(er_print) sample_list
Exp Sel     Total
=== ======= =====
  1 1-6        31
  2 7-10,15    31

lwp_list

显示当前选定的要进行分析的 LWP 的列表。

thread_list

显示当前选定的要进行分析的线程的列表。

cpu_list

显示当前选定的要进行分析的 CPU 的列表。

控制实验数据过滤的命令

可以指定按以下两种方式过滤实验数据：

指定过滤表达式

可以使用 filters 命令指定过滤表达式。

filters filter_exp

filter_exp 是一个表达式，对于应该包括的任何数据记录，其计算结果为真；对于不应包括的记录，其计算结果为假。表达式的语法在表达式语法中介绍。

选择要进行过滤的抽样、线程、LWP 和 CPU

选择列表

选择语法如以下示例所示。该语法用于命令描述。


[experiment-list:]selection-list[+[
experiment-list:]selection-list … ]

可以在每个选择列表前面加上实验列表，用冒号与其隔开且不加空格。可以通过用 + 符号连接多个选择列表来进行多个选择。

实验列表和选择列表具有相同的语法，可以使用关键字 all，也可以使用编号或编号范围 (n-m) 的列表，其中用逗号分隔且不加空格，如以下示例所示。


2,4,9-11,23-32,38,40

可以使用 exp_list 命令确定实验编号。

一些选择示例如下所示。


1:1-4+2:5,6
all:1,3-6

在第一个示例中，从实验 1 选择了对象 1 到 4，从实验 2 选择了对象 5 和 6。在第二个示例中，从所有实验选择了对象 1 以及 3 到 6。对象可以是 LWP、线程或抽样。

选择命令

用于选择 LWP、抽样、CPU 和线程的命令不是独立的。如果某个命令的实验列表与前一个命令的实验列表不同，则按以下方式将来自最后一个命令的实验列表应用于所有三个选择目标－LWP、抽样和线程。

sample_select sample_spec

选择要显示其信息的抽样。命令完成时，会显示所选抽样的列表。

lwp_select lwp_spec

选择要显示其信息的 LWP。命令完成时，会显示所选 LWP 的列表。

thread_select thread_spec

选择要显示其信息的线程。命令完成时，会显示所选线程的列表。

cpu_select cpu_spec

选择要显示其信息的 CPU。命令完成时，会显示所选 CPU 的列表。

控制装入对象展开和折叠的命令

object_list

显示一个由两列组成的列表，包含可用装入对象的状态和名称。在第一列中显示每个装入对象的展开状态，在第二列中显示对象的名称。每个装入对象的名称前有 yes（指示在函数列表中显示该对象的函数（已展开））或 no（指示在函数列表中不显示该对象的函数（已折叠））。已折叠装入对象的所有函数都映射到函数列表中表示整个装入对象的单个条目。

以下是装入对象列表的示例。


(er_print) object_list
Sel Load Object
=== ==================
no  <Unknown>
yes <Freeway>
yes <libCstd_isa.so.1>
yes <libnsl.so.1>
yes <libmp.so.2>
yes <libc.so.1>
yes <libICE.so.6>
yes <libSM.so.6>
yes <libm.so.1>
yes <libCstd.so.1>
yes <libX11.so.4>
yes <libXext.so.0>
yes <libCrun.so.1>
yes <libXt.so.4>
yes <libXm.so.4>
yes <libsocket.so.1>
yes <libgen.so.1>
yes <libcollector.so>
yes <libc_psr.so.1>
yes <ld.so.1>
yes <liblayout.so.1>

object_select object1,object2,...

选择要显示其中函数信息的装入对象。object-list 是装入对象的列表，用逗号分隔且不加空格。如果选择某个装入对象，则会展开其函数，并且在函数列表中显示具有非零度量的所有函数。如果未选择某个装入对象，则会折叠其函数，并且仅显示包含整个装入对象的度量的单个行，而不是显示其各个函数。

装入对象的名称应该为全路径名或基本名称。如果对象名称本身包含逗号，则必须用双引号将名称引起来。

列出度量的命令

以下命令列出当前选定的度量以及所有可用的度量关键字。

metric_list

显示函数列表中当前选定的度量和可以在其他命令（例如 metrics 和 sort）中使用的度量关键字列表，以在函数列表中引用各种类型的度量。

cmetric_list

显示调用者-被调用者列表中当前选定的度量和可以在其他命令（例如 cmetrics 和 csort）中使用的度量关键字列表，以在调用者-被调用者列表中引用各种类型的度量。

注 –

可以将归属度量指定为仅与 cmetrics 命令一起显示，而不是与 metrics 命令或 data_metrics 命令一起显示，而且仅与 callers-callees 命令一起显示，而不是与 functions 命令或 data_objects 命令一起显示。

data_metric_list

显示当前选定的数据派生度量以及所有数据派生报告的度量和关键字名称的列表。列表的显示方式与 metric_list 命令的输出方式相同，但是仅包括那些具有数据派生类型的度量和静态度量。

注 –

可以将数据派生度量指定为仅与 data_metrics 命令一起显示，而不是与 metrics 命令或 cmetrics 命令一起显示，而且仅与 data_objects 命令一起显示，而不是与 functions 命令或 callers-callees 命令一起显示。

indx_metric_list

显示当前选定的索引对象度量。以与 metric_list 命令相同的方式显示列表，但是仅包括那些具有独占类型的度量和静态度量。

控制输出的命令

以下命令控制 er_print 显示输出。

outfile { filename | - }

关闭任何打开的输出文件，然后为后续输出打开 filename。打开 filename 时，将清除任何先前存在的内容。如果指定一个短划线 (-) 而不是 filename，则将输出写入标准输出。如果指定两个短划线 (--) 而不是 filename，则将输出写入标准错误。

appendfile filename

关闭任何打开的输出文件并打开 filename，保留任何先前存在的内容，以便将后续输出附加到文件的结尾。如果 filename 不存在，则 appendfile 命令的功能与 outfile 命令的功能相同。

limit n

将输出限制为报告中的前 n 个条目；n 是一个无符号正整数。

name { long | short } [ :{ shared_object_name | no_shared_object_name } ]"

指定是使用长形式还是短形式的函数名称（仅限 C++ 和 Java）。如果指定了 shared_object_name，则将共享对象名称附加到函数名称。

viewmode { user | expert | machine }

将模式设置为以下模式之一：

user（用户）

对于 Java 实验，显示 Java 线程的 Java 调用栈，而不显示内务处理线程。函数列表包括函数 <JVM-System>，该函数表示来自非 Java 线程的聚集时间。当 JVM 软件不报告 Java 调用栈时，将根据函数 <no Java callstack recorded> 报告时间。

对于 OpenMP 实验，在 OpenMP 运行时执行某些操作时，将显示已协调的主线程调用栈和从属线程调用栈，并添加名称格式为 <OMP-*> 的特殊函数。

expert（专家）

对于 Java 实验，在执行用户的 Java 代码时，将显示 Java 线程的 Java 调用栈；而在执行 JVM 代码或当 JVM 软件不报告 Java 调用栈时，则显示计算机调用栈。显示内务处理线程的计算机调用栈。

对于 OpenMP 实验，显示与 user 模式相同的信息。

machine（计算机）

对于 Java 实验和 OpenMP 实验，显示所有线程的计算机调用栈。

对于除 Java 实验和 OpenMP 实验之外的所有实验，所有三种模式都显示相同的数据。

列显其他信息的命令

header exp_id

显示有关指定实验的描述性信息。exp_id 可以通过 exp_list 命令获得。如果 exp_id 为 all 或未提供，则显示所有已装入实验的信息。

在每个标头后，将列显任何错误或警告。每个实验的标头由一行短划线分隔。

如果实验目录包含名为 notes 的文件，则将该文件的内容添加到标头信息之前。可以通过 collect 命令的 -C “comment” 参数，手动添加、编辑或指定 notes 文件。

exp_id 在命令行上是必需的，但是在脚本中或交互模式下不是必需的。

ifreq

从度量的计数数据写入指令频率列表。指令频率报告只能从计数数据生成。此命令仅在运行 Solaris OS 的 SPARC 处理器上适用。

objects

列出装入对象以及由于使用装入对象而产生的任何错误或警告消息以用于性能分析。可以使用 limit 命令限制列出的装入对象数（请参见控制输出的命令）。

overview exp_id

写出当前为指定实验选择的每个抽样的抽样数据。exp_id 可以通过 exp_list 命令获得。如果 exp_id 为 all 或未提供，则显示所有实验的抽样数据。exp_id 在命令行上是必需的，但是在脚本中或交互模式下不是必需的。

statistics exp_id

写出在指定实验的当前抽样集上聚集的执行统计数据。有关显示的执行统计数据的定义和含义，请参见 getrusage(3C) 和 proc(4) 手册页。执行统计数据包括来自收集器未收集其任何数据的系统线程的统计数据。

exp_id 可以通过 experiment_list 命令获得。如果未提供 exp_id，则显示在每个实验的抽样集上聚集的所有实验的数据总和。如果 exp_id 为 all，则显示每个实验的总和统计和单独统计。

设置缺省值的命令

可以使用以下命令设置 er_print 与性能分析器的缺省值。这些命令只能用于设置缺省值：它们不能用作 er_print 实用程序的输入。可以将它们包括在名为 .er.rc 的缺省文件中。仅适用于性能分析器缺省值的命令在仅为性能分析器设置缺省值的命令中介绍。

可将缺省文件包含在起始目录中以为所有实验设置缺省值，或将其包含在任何其他目录中以在本地设置缺省值。启动 er_print 实用程序、er_src 实用程序或性能分析器时，将扫描当前目录和起始目录以查找缺省文件。如果存在缺省文件，则读取它们，同时也读取系统缺省文件。起始目录中的 .er.rc 文件的缺省值覆盖系统的缺省值，而当前目录中 .er.rc 文件的缺省值覆盖起始目录和系统的缺省值。

注 –

要确保从存储实验的目录读取缺省文件，必须从该目录启动性能分析器或 er_print 实用程序。

缺省文件还可以包括 scc、sthresh、dcc、dthresh、cc、setpath、addpath、pathmap、name、mobj_define、indxobj_define、tabs、rtabs 和 viewmode 命令。可以在缺省文件中包括多个 dmetrics、dsort、addpath、pathmap、mobj_define 和 indxobj_define 命令，并串联来自所有 .er.rc 文件的命令。对于所有其他命令，如果出现多次，则使用第一次出现的该命令，而忽略随后出现的该命令。

dmetrics metric_spec

指定要在函数列表中显示或列显的缺省度量。度量列表的语法和用法在度量列表一节中介绍。列表中度量关键字的顺序确定显示度量的顺序和它们在性能分析器的度量选择器中出现的顺序。

通过在列表中每个度量名称第一次出现的地方之前添加对应的归属度量，可从函数列表缺省度量派生调用者-被调用者列表的缺省度量。

dsort metric_spec

指定函数列表将按其排序的缺省度量。排序度量是该列表中与任何已装入实验中的度量匹配的第一个度量，且受到以下条件的限制：

度量列表的语法和用法在度量列表一节中介绍。

调用者-被调用者列表的缺省排序度量是对应于函数列表的缺省排序度量的归属度量。

en_desc { on | off | =regexp}

将读取后续实验的模式设置为 on（启用所有后续实验）或 off（禁用所有后续实验）。如果使用 =regexp，则启用其后代或可执行文件名称与正则表达式匹配的那些实验的数据。

仅为性能分析器设置缺省值的命令

tabs tab_spec

设置在分析器中可见的一组缺省标签。标签由生成对应报告的 er_print 命令命名（包括用于内存对象标签的 mobj_type 或用于索引对象标签的 indxobj_type）。timeline 指定“时间线”标签，而 headers 指定“实验”标签。

仅显示已装入实验中的数据所支持的那些标签。

rtabs tab_spec

设置使用 tha 命令调用分析器时可见的一组缺省标签，以便检查线程分析器实验。仅显示已装入实验中的数据所支持的那些标签。

tlmode tl_mode

设置性能分析器的“时间线”标签的显示模式选项。选项列表是一个冒号分隔列表。下表介绍了允许的选项。

表 6–6 时间线显示模式选项

选项 

含义 

lw[p]

显示 LWP 的事件 

t[hread]

显示线程的事件 

c[pu]

显示 CPU 的事件 

r[oot]

在根上对齐调用栈 

le[af]

在叶上对齐调用栈 

d[epth] nn

设置可以显示的调用栈的最大深度 

选项 lwp、thread 和 cpu 是互斥的，root 和 leaf 也是互斥的。如果在列表中包括一组互斥选项中的多个，则仅使用最后一个选项。

tldata tl_data

选择在性能分析器的“时间线”标签中显示的缺省数据类型。类型列表中的类型由冒号分隔。下表列出了允许的类型。

表 6–7 时间线显示数据类型

类型 

含义 

sa[mple]

显示抽样数据 

c[lock]

显示时钟分析数据 

hw[c]

显示硬件计数器分析数据 

sy[nctrace]

显示线程同步跟踪数据 

mp[itrace]

显示 MPI 跟踪数据 

he[aptrace]

显示堆跟踪数据 

杂项命令

mapfile load-object { mapfilename | - }

将指定装入对象的映射文件写入文件 mapfilename。如果指定一个短划线 (-) 而不是 mapfilename，则 er_print 将映射文件写入标准输出。

procstats

列显处理数据的累积统计数据。

script file

处理脚本文件 file 中的附加命令。

version

列显 er_print 实用程序的当前版本号。

quit

终止当前脚本的处理，或者退出交互模式。

help

列显 er_print 命令的列表。

表达式语法

定义过滤器的表达式和用于计算内存对象索引的表达式使用通用语法。

语法将表达式指定为运算符和操作数的组合。对于过滤器，如果表达式的计算结果为真，则包括包；如果表达式的计算结果为假，则排除包。对于内存对象或索引对象，表达式的计算结果为一个索引，该索引定义包中引用的特定内存对象或索引对象。

表达式中的操作数可以是常量、数据记录中的字段（包括 THRID、LWPID、CPUID、STACK、LEAF、VIRTPC、PHYSPC、VADDR、PADDR、DOBJ、TSTAMP、SAMPLE、EXPID、PID）或内存对象的名称。运算符包括常见的逻辑运算符和算术（包括移位）运算符（在 C 表示法中，具有 C 优先级规则），以及用于确定某个元素是否位于集中的运算符 (IN) 或用于确定某组元素中的任一元素或全部元素是否包含在集中的运算符（分别对应 SOME IN 或 IN）。如在 C 中那样指定 If-then-else 结构（使用 ? 和 : 运算符）。使用圆括号以确保正确解析所有表达式。在 er_print 命令行上，不能将表达式拆分为多行。在脚本中或命令行上，如果表达式包含空格，则必须用双引号将其引起来。

过滤表达式的计算结果为布尔值。如果应该包括包，则计算结果为真，如果不应该包括包，则计算结果为假。线程、LWP、CPU、实验 id、进程 pid 和抽样过滤基于相应关键字和整数之间的关系表达式，或者使用 IN 运算符和逗号分隔的整数列表。

可通过在 TSTAMP 和时间（提供整数纳秒，从将要处理其包的实验开始时算起）之间指定一个或多个关系表达式来使用时间过滤。抽样的时间可以使用 overview 命令获得。overview 命令中的时间以秒提供，必须转换为纳秒以用于时间过滤。时间还可以从分析器中的“时间线”显示获得。

函数过滤可以基于叶函数或栈中的任何函数。按叶函数进行过滤是通过 LEAF 关键字和整型函数 id 之间的关系表达式指定的，或者使用 IN 运算符和结构 FNAME("regexp")，其中 regexp 是正则表达式，如 regexp(5) 手册页中所指定的那样。函数的整个名称（如 name 的当前设置所指定）必须匹配。

可以通过确定结构 FNAME("regexp") 中的任何函数是否位于由关键字 STACK: (FNAME("myfunc") SOME IN STACK) 表示的函数数组中来指定基于调用栈中的任何函数的过滤。

数据对象过滤类似于栈函数过滤，使用 DOBJ 关键字和结构 DNAME("regexp")（括在圆括号中）。

内存对象过滤是使用内存对象的名称（如 mobj_list 命令中所示）和对象的整型索引或对象集的索引来指定的。（<Unknown> 内存对象的索引是 -1。）

索引对象过滤是使用索引对象的名称（如 indxobj_list 命令中所示）和对象的整型索引或对象集的索引来指定的。（<Unknown> 索引对象的索引是 -1。）

数据对象过滤和内存对象过滤仅对具有数据空间数据的硬件计数器包有意义；此类过滤将排除所有其他包。

虚拟地址或物理地址的直接过滤是通过 VADDR 或 PADDR 与地址之间的关系表达式指定的。

内存对象定义（请参见mobj_define mobj_type index_exp）使用其计算结果为整型索引的表达式（使用 VADDR 关键字或 PADDR 关键字）。该定义仅适用于内存计数器和数据空间数据的硬件计数器包。该表达式应该返回整数，对于 <Unknown> 内存对象，则返回 -1。

索引对象定义（请参见indxobj_define indxobj_type index_exp）使用其计算结果为整型索引的表达式。该表达式应该返回整数，对于 <Unknown> 索引对象，则返回 -1。

er_print 命令示例