rocprofiler-systems-instrumenting-binaries

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Instrumenting Binaries

对二进制文件进行插桩

rocprof-sys-instrument
decides which functions of a program get instrumented and either does it while the program runs or writes a new instrumented binary. For the full, current flag list run
rocprof-sys-instrument --help
(use
--help | grep -A3 -- --<flag>
for one flag).
rocprof-sys-instrument
决定程序中的哪些函数会被插桩,并且既可以在程序运行时执行插桩,也可以生成一个新的已插桩二进制文件。要获取当前完整的 flag 列表,请运行
rocprof-sys-instrument --help
(如需查看单个 flag,可使用
--help | grep -A3 -- --<flag>
)。

How to answer

如何回答

Keep answers short: under about 1200 characters unless the user asks for more. Lead with the direct answer and the command, then add only the caveats from this skill that apply to the question (for example: binary rewrite skips shared libraries,
-MR
ignores
-R
,
-l
pairs with a lower
-i
, how to list modules with
--print-available
). Do not add alternatives or background nobody asked for.
回答应保持简短:除非用户要求更多内容,否则控制在约 1200 个字符以内。先直接给出答案和命令,然后只补充本 skill 中与问题相关的注意事项(例如:二进制重写会跳过共享库,
-MR
会忽略
-R
,
-l
需要搭配一个更低的
-i
,如何使用
--print-available
列出模块)。不要添加用户未询问的替代方案或背景信息。

Prerequisites

前置条件

  • rocprof-sys-instrument
    and
    rocprof-sys-run
    on
    PATH
    ; if not, run
    source <install-prefix>/share/rocprofiler-systems/setup-env.sh
    .
  • Build the target with
    -g
    when you can: modules are then source files and the tool can report file and line information. Without debug info a whole binary is one module named after the binary.
  • rocprof-sys-instrument
    和
    rocprof-sys-run
    必须位于
    PATH
    中;如果不在,请运行
    source <install-prefix>/share/rocprofiler-systems/setup-env.sh
    。
  • 尽可能使用
    -g
    构建目标程序:此时模块对应源文件,工具可以报告文件和行号信息。没有调试信息时,整个二进制文件会被视为一个模块,并以该二进制文件命名。

Runtime instrumentation vs binary rewrite

运行时插桩与二进制重写

Runtime instrumentationBinary rewrite
Selected bythe default (no
-o
)
-o [<output>]
Command
rocprof-sys-instrument [opts] -- ./app args
rocprof-sys-instrument [opts] -o app.inst -- ./app
What gets instrumentedthe executable and the shared libraries it loadsonly the target's own code; shared libraries are not instrumented
Cost (upstream guidance)more memory, slower to set up, more run-time overheadmuch faster to set up, lower overhead
Runs the appyes, immediately, with
args
no; run
rocprof-sys-run -- ./app.inst args
later
Arguments after the targetpassed to the appignored (give them when you run the result)
  • Pick runtime when the performance of the libraries the app loads matters.
  • Pick binary rewrite for the lowest overhead, for repeated runs, and for MPI applications (upstream guidance).
  • --exe-only
    (runtime only) leaves every shared library out;
    --max-library-functions N
    skips shared libraries with more than
    N
    functions (default 20000;
    0
    disables the check).
  • -o
    with no file name writes
    <name>.inst
    in the current directory (target in the current directory) or
    instrumented/<name>
    for a library.
运行时插桩二进制重写
选择方式默认模式(无
-o
)
-o [<output>]
命令
rocprof-sys-instrument [opts] -- ./app args
rocprof-sys-instrument [opts] -o app.inst -- ./app
插桩对象可执行文件及其加载的共享库仅目标程序自身的代码;共享库不会被插桩
成本(上游指南)占用更多内存、设置更慢、运行时开销更大设置快得多、开销更低
运行应用是,立即使用
args
运行
否;稍后运行
rocprof-sys-run -- ./app.inst args
目标程序后的参数传递给应用会被忽略(运行结果时应传入这些参数)
  • 当应用所加载库的性能很重要时,选择 runtime。
  • 若要获得最低开销、重复运行或运行 MPI 应用,选择 binary rewrite(上游指南)。
  • --exe-only
    (仅限运行时模式)会排除所有共享库;
    --max-library-functions N
    会跳过函数数超过
    N
    的共享库(默认值为 20000;
    0
    表示禁用此检查)。
  • -o
    后未指定文件名时,会在当前目录写入
    <name>.inst
    (目标位于当前目录时),或为库写入
    instrumented/<name>
    。

Function vs module

函数与模块

  • A function is one symbol, for example
    big_a
    or
    Domain::BuildMesh
    .
  • A module is the container a function is defined in: its source file when the binary has debug info (
    /path/mod_a.cpp
    ), otherwise the binary or library itself (
    /path/app
    ). Shared libraries appear as their own modules in runtime mode.
bash
rocprof-sys-instrument --simulate -o app.inst --print-available modules   -- ./app
rocprof-sys-instrument --simulate -o app.inst --print-available functions -- ./app
rocprof-sys-instrument --simulate -o app.inst --print-available pair      -- ./app
pair
prints one
[module] --> [function][#instructions]
line per function. Module options (
-MI
,
-ME
,
-MR
) act on every function in the matching modules; function options (
-I
,
-E
,
-R
) act on individual functions.
  • 函数是一个符号,例如
    big_a
    或
    Domain::BuildMesh
    。
  • 模块是定义函数的容器:二进制文件包含调试信息时,模块是其源文件(
    /path/mod_a.cpp
    );否则模块就是二进制文件或库本身(
    /path/app
    )。在运行时模式下,共享库会作为独立模块出现。
bash
rocprof-sys-instrument --simulate -o app.inst --print-available modules   -- ./app
rocprof-sys-instrument --simulate -o app.inst --print-available functions -- ./app
rocprof-sys-instrument --simulate -o app.inst --print-available pair      -- ./app
pair
会为每个函数输出一行
[module] --> [function][#instructions]
。 模块选项(
-MI
、
-ME
、
-MR
)会作用于匹配模块中的每个函数;函数选项(
-I
、
-E
、
-R
)则作用于单个函数。

Including, excluding and restricting

包含、排除与限制

OptionMeaning
-I
/
-MI
(include)
Force these in, even if the size heuristics would skip them. Does not narrow anything else.
-R
/
-MR
(restrict)
Instrument only what matches, ignoring the size heuristics.
-E
/
-ME
(exclude)
Never instrument these. Always applied, and wins over include and restrict.
Matching rules (all verified):
  • Patterns are regular expressions matched anywhere in the name (substring, not anchored).
    tiny
    matches
    tiny_a
    and
    tiny_b
    ; write
    ^tiny_a$
    for an exact match.
  • Several patterns after one option are OR'd:
    -I tiny_a medium_b
    is the same as
    -I 'tiny_a|medium_b'
    .
  • Module patterns match the module name (the source file or binary path). Function patterns match the function name, and also the signature when
    --label args
    is set (so
    -I '\(long int\)$'
    only works together with
    --label args
    ).
  • Exclude beats include at any level:
    -ME 'mod_' -I tiny_a
    instruments nothing.
  • -MR mod_a
    instruments every function of
    mod_a
    , including tiny ones and ones with loops, regardless of the size thresholds.
Gotcha: if you give both
--module-restrict
and
--function-restrict
, the function restriction is silently ignored.
-MR mod_a -R '^medium_b$'
instrumented all of
mod_a
, not the union the upstream docs describe. Use one of the two, or combine
-MR
with
-E
.
Examples:
bash
undefined
选项含义
-I
/
-MI
(include)
强制插桩这些项,即使大小启发式规则会跳过它们。该选项不会缩小其他匹配范围。
-R
/
-MR
(restrict)
仅插桩匹配项,并忽略大小启发式规则。
-E
/
-ME
(exclude)
永不插桩这些项。该规则始终生效,优先级高于 include 和 restrict。
匹配规则(均已验证):
  • pattern 是正则表达式,会在名称中的任意位置匹配(即子字符串匹配,不锚定)。
    tiny
    可匹配
    tiny_a
    和
    tiny_b
    ;如需精确匹配,请编写
    ^tiny_a$
    。
  • 同一选项后的多个 pattern 之间采用 OR 关系:
    -I tiny_a medium_b
    等同于
    -I 'tiny_a|medium_b'
    。
  • 模块 pattern 匹配模块名称(源文件或二进制文件路径)。函数 pattern 匹配函数名称;设置
    --label args
    后还会匹配函数签名(因此
    -I '\(long int\)$'
    只有与
    --label args
    一起使用时才有效)。
  • 任意层级都是 exclude 优先于 include:
    -ME 'mod_' -I tiny_a
    不会插桩任何内容。
  • -MR mod_a
    会插桩
    mod_a
    中的每个函数,包括函数体很小或包含循环的函数,且不受大小阈值限制。
注意:如果同时使用
--module-restrict
和
--function-restrict
,函数限制会被静默忽略。
-MR mod_a -R '^medium_b$'
会插桩
mod_a
中的所有函数,而不是上游文档所描述的并集。请只使用其中一种,或将
-MR
与
-E
结合使用。
示例:
bash
undefined

Only one source file

Only one source file

rocprof-sys-instrument -o app.inst -MR 'solver.cpp$' -- ./app
rocprof-sys-instrument -o app.inst -MR 'solver.cpp$' -- ./app

Everything the heuristics pick, minus one noisy library

Everything the heuristics pick, minus one noisy library

rocprof-sys-instrument -o app.inst -ME 'libm.so' -- ./app
rocprof-sys-instrument -o app.inst -ME 'libm.so' -- ./app

Add a small function the heuristics skip

Add a small function the heuristics skip

rocprof-sys-instrument -o app.inst -I '^small_helper$' -- ./app
undefined
rocprof-sys-instrument -o app.inst -I '^small_helper$' -- ./app
undefined

Dry run

试运行(Dry Run)

A dry run shows what would be instrumented without instrumenting anything.
bash
rocprof-sys-instrument --simulate [options] -- ./app
rocprof-sys-instrument --simulate -o app.inst --print-instrumented pair -- ./app
rocprof-sys-instrument --dump-info --simulate -o app.inst -- ./app
What
--simulate
does (verified):
  • Exits after the analysis. It does not run the application and does not write the rewritten binary, even with
    -o
    .
  • Prints a per-module summary (
    N instrumented funcs in <module>
    ).
  • With
    --print-available
    ,
    --print-instrumented
    ,
    --print-excluded
    ,
    --print-coverage
    or
    --print-overlapping
    it also prints those lists. Each takes
    functions
    ,
    modules
    or
    pair
    ; the
    +
    forms (
    functions+
    ,
    pair+
    ) also show the function signature when
    --label args
    is used.
What
--dump-info
does:
  • Writes
    available
    ,
    instrumented
    ,
    excluded
    and
    overlapping
    reports as
    .txt
    and
    .json
    to
    rocprofsys-<name>-output/instrumentation/
    , where
    <name>
    is the target (runtime) or the
    -o
    output name (rewrite, e.g.
    rocprofsys-app.inst-output
    ).
  • --print-format json
    (or
    txt
    ) limits the formats. Set
    ROCPROFSYS_OUTPUT_PATH
    to move the directory.
    --print-dir
    had no effect in either build tested.
  • The
    .txt
    files list address, address range, instruction count, linkage, visibility, module and function. The
    .json
    files add a per-function
    heuristics
    block (see "Why is a function missing?").
  • Without
    --simulate
    ,
    --dump-info
    still produces the rewritten binary as usual.
Workflow: dry run, read
instrumented
and
excluded
, adjust the regexes or thresholds, repeat, then drop
--simulate
.
试运行可以显示将要插桩的内容,而不会实际执行任何插桩。
bash
rocprof-sys-instrument --simulate [options] -- ./app
rocprof-sys-instrument --simulate -o app.inst --print-instrumented pair -- ./app
rocprof-sys-instrument --dump-info --simulate -o app.inst -- ./app
--simulate
的行为(已验证):
  • 分析完成后退出。它不会运行应用,即使使用了
    -o
    ,也不会写入重写后的二进制文件。
  • 输出按模块汇总的信息(
    N instrumented funcs in <module>
    )。
  • 与
    --print-available
    、
    --print-instrumented
    、
    --print-excluded
    、
    --print-coverage
    或
    --print-overlapping
    一起使用时,还会输出相应列表。每个选项都接受
    functions
    、
    modules
    或
    pair
    ;带
    +
    的形式(如
    functions+
    、
    pair+
    )在使用
    --label args
    时还会显示函数签名。
--dump-info
的行为:
  • 将
    available
    、
    instrumented
    、
    excluded
    和
    overlapping
    报告以
    .txt
    和
    .json
    格式写入
    rocprofsys-<name>-output/instrumentation/
    ,其中
    <name>
    是运行时模式下的目标名称,或重写模式下
    -o
    的输出名称(例如
    rocprofsys-app.inst-output
    )。
  • --print-format json
    (或
    txt
    )用于限制输出格式。设置
    ROCPROFSYS_OUTPUT_PATH
    可以移动目录。在测试过的两个构建中,
    --print-dir
    均未产生效果。
  • .txt
    文件会列出地址、地址范围、指令数、linkage、visibility、模块和函数。
    .json
    文件还会为每个函数增加一个
    heuristics
    块(参见“函数为何缺失?”)。
  • 不使用
    --simulate
    时,
    --dump-info
    仍会照常生成重写后的二进制文件。
工作流:先执行试运行,读取
instrumented
和
excluded
,调整 regex 或阈值后重复执行,最后移除
--simulate
。

Granularity

粒度

A function is instrumented only if it passes both size checks (verified):
  • at least
    --min-instructions
    instructions (default 1024), and
  • an address range of at least
    --min-address-range
    bytes (default 4 x the instruction minimum, so 4096).
Interactions that surprise people:
  • Giving only
    -i N
    sets the address-range minimum to 0 (only instruction count matters), and giving only
    -r N
    sets the instruction minimum to 0. Giving both applies both.
    -i 0
    or
    -r 0
    therefore disables both size checks. It does not instrument every function: a function must still have at least 2 instructions, be instrumentable by Dyninst, and pass the exclude, overlap, trap, linkage and visibility checks, and it is never taken from the profiler's own or system modules.
  • The environment variable
    ROCPROFSYS_DEFAULT_MIN_INSTRUCTIONS
    changes the default instruction minimum, and the default range with it.
  • Functions that contain loops use
    --min-instructions-loop
    and
    --min-address-range-loop
    , which follow the non-loop values unless set. These options decide whether a function with a loop is instrumented at all.
  • -l
    /
    --instrument-loops
    additionally instruments the loops inside instrumented functions. In a profile each loop shows as a child entry named with its source range, for example
    loop_a [{449,54}-{449,83}]
    , and the function's own self time drops accordingly.
Example from a small test program (instruction counts: 7, 16, 79, 429, 3657):
OptionsInstrumented functions
defaultonly the 3657-instruction function
-i 100
the 429 and 3657 functions
-i 20
79, 429 and 3657
-i 0
all five
-i 50 -r 1000
429 and 3657 (the 79-instruction function is only 278 bytes)
More detail means more overhead and a bigger trace. Lower the thresholds or add
-l
to see inside hot code; raise them, restrict to modules, or use
--exe-only
to cut overhead. Other gates (
--dynamic-callsites
,
--traps
,
--loop-traps
,
--allow-overlapping
,
--linkage
,
--visibility
) are described in
--help
.
只有同时通过两项大小检查的函数才会被插桩(已验证):
  • 指令数至少达到
    --min-instructions
    (默认值为 1024);以及
  • 地址范围至少达到
    --min-address-range
    字节(默认是指令最小值的 4 倍,即 4096)。
一些容易令人意外的行为:
  • 只提供
    -i N
    时,地址范围最小值会设为 0(此时仅指令数起作用);只提供
    -r N
    时,指令数最小值会设为 0。同时提供两者则会同时应用两项检查。因此,
    -i 0
    或
    -r 0
    会禁用两项大小检查。但这并不意味着每个函数都会被插桩:函数仍必须至少包含 2 条指令、能够由 Dyninst 插桩,并通过 exclude、overlap、trap、linkage 和 visibility 检查;同时,profiler 自身或系统模块中的函数永远不会被选取。
  • 环境变量
    ROCPROFSYS_DEFAULT_MIN_INSTRUCTIONS
    会更改默认指令数最小值,并随之更改默认范围。
  • 包含循环的函数使用
    --min-instructions-loop
    和
    --min-address-range-loop
    ;除非显式设置,否则它们沿用非循环函数对应的值。这些选项决定包含循环的函数是否会被插桩。
  • -l
    /
    --instrument-loops
    还会插桩已插桩函数内部的循环。在 profile 中,每个循环都会显示为一个子条目,名称包含其源代码范围,例如
    loop_a [{449,54}-{449,83}]
    ,相应地,函数自身的 self time 会减少。
以下结果来自一个小型测试程序(指令数分别为 7、16、79、429、3657):
选项被插桩的函数
默认值仅包含 3657 条指令的函数
-i 100
429 条和 3657 条指令的函数
-i 20
79 条、429 条和 3657 条指令的函数
-i 0
全部五个函数
-i 50 -r 1000
429 条和 3657 条指令的函数(79 条指令的函数仅有 278 字节)
收集的信息越详细,开销越大,trace 也会越大。降低阈值或添加
-l
可以查看热点代码内部;提高阈值、将范围限制到特定模块或使用
--exe-only
可以减少开销。其他门控条件(
--dynamic-callsites
、
--traps
、
--loop-traps
、
--allow-overlapping
、
--linkage
、
--visibility
)请参阅
--help
。

Why is a function missing, or why is there too much?

函数为何缺失,或为何数据过多?

Missing function:
  1. List what was skipped:
    --simulate --print-excluded pair
    , or
    --dump-info --simulate
    .
  2. Open
    excluded.json
    , find the function and read its
    heuristics
    block (
    should_instrument: false
    is the verdict). The fields come in two kinds, and the cause is a different value in each.
    • Capability fields: false is the cause.
      is_instrumentable
      ,
      can_instrument_entry
      and
      can_instrument_exit
      false mean Dyninst has no usable entry or exit point for the function. No option fixes that, so accept the gap or instrument its callers.
    • Constraint fields: true is the cause.
      • is_address_range_constrained
        ,
        is_num_instructions_constrained
        (and the
        is_loop_*
        variants): too small. Lower
        -i
        /
        -r
        , or add
        -I
        .
      • is_user_excluded
        : one of your
        -E
        /
        -ME
        patterns matches it.
      • is_user_restricted
        : a
        -R
        /
        -MR
        pattern did not match it.
      • is_overlapping_constrained
        : needs
        --allow-overlapping
        .
      • is_entry_trap_constrained
        ,
        is_exit_trap_constrained
        : needs
        --traps
        .
      • is_linkage_constrained
        ,
        is_visibility_constrained
        : see
        --linkage
        ,
        --visibility
        .
      • is_internal_constrained
        : it belongs to the profiler's own libraries.
      • is_module_constrained
        : its module is one the profiler never instruments (system library, Dyninst, or its own libraries).
      • is_routine_constrained
        : its name is one the profiler never instruments.
    • No field at all: a function with fewer than 2 instructions is always skipped. If every capability field is true and no constraint field is true, check
      num_instructions
      (verified: a 1-instruction function stays excluded even with
      -i 0
      ).
  3. If the function is in a shared library, remember binary rewrite never sees it.
Too much data or too slow: raise
-i
, restrict to the modules you care about (
-MR
), exclude noisy ones (
-ME
), drop
-l
, or add
--exe-only
.
函数缺失:
  1. 列出被跳过的内容:
    --simulate --print-excluded pair
    ,或使用
    --dump-info --simulate
    。
  2. 打开
    excluded.json
    ,找到该函数并读取其
    heuristics
    块(
    should_instrument: false
    是最终判定)。这些字段分为两类,不同类别中导致缺失的原因取值也不同。
    • 能力字段:false 才是原因。
      is_instrumentable
      、
      can_instrument_entry
      和
      can_instrument_exit
      为 false,表示 Dyninst 无法为该函数找到可用的入口点或出口点。没有选项可以解决此问题,只能接受该缺口或对其调用者进行插桩。
    • 约束字段:true 才是原因。
      • is_address_range_constrained
        、
        is_num_instructions_constrained
        (以及
        is_loop_*
        变体):函数太小。降低
        -i
        /
        -r
        ,或添加
        -I
        。
      • is_user_excluded
        :某个
        -E
        /
        -ME
        pattern 与该函数匹配。
      • is_user_restricted
        :某个
        -R
        /
        -MR
        pattern 与该函数不匹配。
      • is_overlapping_constrained
        :需要使用
        --allow-overlapping
        。
      • is_entry_trap_constrained
        、
        is_exit_trap_constrained
        :需要使用
        --traps
        。
      • is_linkage_constrained
        、
        is_visibility_constrained
        :请参阅
        --linkage
        、
        --visibility
        。
      • is_internal_constrained
        :该函数属于 profiler 自身的库。
      • is_module_constrained
        :该函数所属模块是 profiler 从不插桩的模块(系统库、Dyninst 或其自身库)。
      • is_routine_constrained
        :该函数名称属于 profiler 从不插桩的名称。
    • 完全没有对应字段: 包含少于 2 条指令的函数始终会被跳过。如果所有能力字段均为 true,且没有任何约束字段为 true,请检查
      num_instructions
      (已验证:即使使用
      -i 0
      ,仅包含 1 条指令的函数仍会被排除)。
  3. 如果该函数位于共享库中,请记住二进制重写模式看不到共享库。
数据过多或速度过慢:提高
-i
,将范围限制到关注的模块(
-MR
),排除噪声较大的模块(
-ME
),移除
-l
,或添加
--exe-only
。

Libraries, RPATH and troubleshooting

库、RPATH 与故障排除

Rewriting a shared library so a normal executable loads the instrumented copy:
bash
rocprof-sys-instrument -o ./app.inst -- ./app
mkdir inst && rocprof-sys-instrument -o inst/libfoo.so -- ./libfoo.so
LD_LIBRARY_PATH=$PWD/inst:$LD_LIBRARY_PATH rocprof-sys-run -- ./app.inst
ldd ./app.inst | grep libfoo      # must resolve into inst/
  • Keep the same file name for the rewritten library (
    libfoo.so
    , or the soname that
    ldd
    shows) and write it to a different directory.
  • RPATH vs RUNPATH: the loader searches
    DT_RPATH
    directories before
    LD_LIBRARY_PATH
    , so if the original library is in an RPATH directory it is loaded instead of your rewritten copy. If the RPATH directories do not contain the library,
    LD_LIBRARY_PATH
    is still used, and a binary with
    RUNPATH
    searches
    LD_LIBRARY_PATH
    first. Check with
    objdump -p <exe> | egrep 'RPATH|RUNPATH'
    and
    ldd
    . Only patch the binary when
    ldd
    shows the original library. Relink with
    -Wl,--enable-new-dtags
    , or change the entry with
    patchelf
    :
    patchelf --remove-rpath <exe>
    makes
    LD_LIBRARY_PATH
    win, and
    patchelf --set-rpath <dir> <exe>
    writes a
    RUNPATH
    , so it does too. Adding
    --force-rpath
    keeps a
    DT_RPATH
    , which brings the problem back.
  • Library as a runtime target:
    rocprof-sys-instrument -- ./libfoo.so
    prints "is not executable ... Switching to binary rewrite mode and assuming '--simulate --all-functions'", so you get a dry-run approximation and no run.
    -f/--force
    is only meant for executables whose name looks like a library; forcing it on a real
    .so
    aborted inside Dyninst in testing.
  • Main function not found: pass it with
    -m <symbol>
    (or
    --main-function
    ).
  • "Failed to transform trace ... in function '<f>'" (upstream guidance, not reproduced): add
    -E '<f>'
    . Functions that share code with it can still pull it in; exclude those too, or exclude the whole module with
    -ME
    .
重写共享库,使普通可执行文件加载已插桩副本:
bash
rocprof-sys-instrument -o ./app.inst -- ./app
mkdir inst && rocprof-sys-instrument -o inst/libfoo.so -- ./libfoo.so
LD_LIBRARY_PATH=$PWD/inst:$LD_LIBRARY_PATH rocprof-sys-run -- ./app.inst
ldd ./app.inst | grep libfoo      # must resolve into inst/
  • 重写后的库必须保持相同文件名(
    libfoo.so
    ,或
    ldd
    显示的 soname),并写入另一个目录。
  • RPATH 与 RUNPATH: 加载器会先搜索
    DT_RPATH
    目录,再搜索
    LD_LIBRARY_PATH
    。因此,如果原始库位于 RPATH 目录中,加载器会加载原始库,而不是重写后的副本。 如果 RPATH 目录中没有该库,仍会使用
    LD_LIBRARY_PATH
    ;带有
    RUNPATH
    的二进制文件则会优先搜索
    LD_LIBRARY_PATH
    。 可使用
    objdump -p <exe> | egrep 'RPATH|RUNPATH'
    和
    ldd
    进行检查。仅当
    ldd
    显示原始库时才需要修补二进制文件。使用
    -Wl,--enable-new-dtags
    重新链接,或使用
    patchelf
    修改条目:
    patchelf --remove-rpath <exe>
    可让
    LD_LIBRARY_PATH
    优先,
    patchelf --set-rpath <dir> <exe>
    会写入
    RUNPATH
    ,同样可让
    LD_LIBRARY_PATH
    优先。添加
    --force-rpath
    会保留
    DT_RPATH
    ,从而重新引入该问题。
  • 将库作为运行时目标:
    rocprof-sys-instrument -- ./libfoo.so
    会输出
    is not executable ... Switching to binary rewrite mode and assuming '--simulate --all-functions'
    ,因此只会得到近似试运行结果,且不会实际运行。
    -f
    /
    --force
    仅用于名称看起来像库的可执行文件;测试中,将其强制用于真正的
    .so
    会导致 Dyninst 内部中止。
  • 找不到 main 函数: 使用
    -m <symbol>
    (或
    --main-function
    )传入该符号。
  • Failed to transform trace ... in function '<f>'
    (上游指南,未复现):添加
    -E '<f>'
    。与其共享代码的函数仍可能将其带入;请同时排除这些函数,或使用
    -ME
    排除整个模块。

Running the result and embedding defaults

运行结果与嵌入默认值

  • Run a rewritten binary with
    rocprof-sys-run -- ./app.inst args
    ; the instrumented functions then appear in the profile or trace like any other.
  • --env VAR=VALUE ...
    embeds defaults in the new binary so a later session does not need to export them. A variable set at run time still overrides the embedded value (verified with
    ROCPROFSYS_PROFILE
    ).
  • --label args file line return
    adds that information to function names (for example
    big_a(long int)
    with
    args
    ).
  • -M sampling
    instruments only
    main
    to start and stop the sampler (verified), and is deprecated upstream; for sampling use
    rocprof-sys-sample
    or a preset.
  • 使用
    rocprof-sys-run -- ./app.inst args
    运行重写后的二进制文件;已插桩的函数随后会像其他函数一样出现在 profile 或 trace 中。
  • --env VAR=VALUE ...
    会将默认值嵌入新二进制文件,使后续会话无需导出这些变量。在运行时设置变量仍会覆盖嵌入值(已通过
    ROCPROFSYS_PROFILE
    验证)。
  • --label args file line return
    会将这些信息添加到函数名称中,例如使用
    args
    后显示为
    big_a(long int)
    。
  • -M sampling
    仅对
    main
    进行插桩,以启动和停止 sampler(已验证),且上游已弃用该选项;对于 sampling,请使用
    rocprof-sys-sample
    或 preset。

Common Mistakes

常见错误

MistakeFix
Expecting binary rewrite to instrument shared librariesIt only covers the target's own code. Use runtime mode, or rewrite the library too.
Using
-I
to narrow the selection
-I
only adds. Narrow with
-R
/
-MR
, or exclude with
-E
/
-ME
.
Writing
-I tiny
and expecting an exact match
Patterns are unanchored substrings. Use
^tiny_a$
.
Combining
-MR
and
-R
The function restriction is ignored. Use one, or
-MR
plus
-E
.
Lowering only
-i
and expecting range to still apply
One option given sets the other to 0. Pass both to apply both.
Passing app arguments after the target in a rewriteThey are ignored; pass them to
rocprof-sys-run -- ./app.inst args
.
Putting a rewritten library next to a binary with
DT_RPATH
LD_LIBRARY_PATH
is ignored. Check with
objdump -p
and relink or patch the rpath.
Expecting
--simulate -o
to produce the binary
A dry run writes only reports; remove
--simulate
.
Relying on
--print-dir
It had no effect in tested builds; use
ROCPROFSYS_OUTPUT_PATH
.
错误修复方式
期望二进制重写能够插桩共享库它只覆盖目标程序自身的代码。请使用运行时模式,或同时重写该库。
使用
-I
缩小选择范围
-I
只会添加项目。请使用
-R
/
-MR
缩小范围,或使用
-E
/
-ME
排除。
编写
-I tiny
并期望精确匹配
Pattern 是未锚定的子字符串匹配。请使用
^tiny_a$
。
同时使用
-MR
和
-R
函数限制会被忽略。请只使用其中一种,或使用
-MR
加
-E
。
只降低
-i
,并期望范围检查仍然生效
只提供一个选项会将另一个设为 0。需要同时应用两项检查时,请将两者都传入。
在重写模式下将应用参数放在目标程序之后这些参数会被忽略;请将它们传给
rocprof-sys-run -- ./app.inst args
。
将重写后的库放在带有
DT_RPATH
的二进制文件旁边
LD_LIBRARY_PATH
会被忽略。请使用
objdump -p
检查,并重新链接或修补 rpath。
期望
--simulate -o
生成二进制文件
试运行只写入报告;请移除
--simulate
。
依赖
--print-dir
在测试过的构建中它没有效果;请使用
ROCPROFSYS_OUTPUT_PATH
。