插桩

仪器化在 onnx-mlir 中进行原型设计，可用于调试运行时问题。

为仪器化进行编译

默认情况下，仪器化是关闭的。您需要使用以下命令行选项来启用它。通过使用 --instrument-stage 选项，仪器化过程将在某些阶段插入。例如，当您指定 Onnx 时，仪器化将在 onnx-to-onnx 转换之后插入，以获得 onnx 级别的性能分析。 --instrument-ops 选项是指定要进行仪器化的操作。例如，您可以使用 onnx.Conv 来表示 onnx 的 Conv 操作。此外，您还可以使用星号，如 onnx.*，表示所有 onnx 操作，或者使用 , 分隔的两个表达式，如 onnx.Conv,onnx.Add，表示 Conv 和 Add 操作。 --InstrumentBeforeOp 和 --InstrumentAfterOp 是在指定操作之前和/或之后插入仪器化的选项。当您使用 --instrument-ops=onnx.* --InstrumentBeforeOp --InstrumentAfterOp 时，仪器化将在所有 onnx 操作之前和之后插入。对于 NNPA，还提供了 ZHigh 和 ZLow 的附加阶段。您可以使用 --instrument-stage=ZHigh 和 --instrument-ops=onnx.*,zhigh.* 来获取 onnx 和 zhigh 操作的性能分析，并使用 --instrument-stage=ZLow 和 --instrument-ops=zlow.* 来获取 zlow 操作的性能分析。

  --instrument-stage=<value>                        - Specify stage to be instrumented:
    =Onnx                                             -   Profile for onnx ops. For NNPA, profile onnx ops before lowering to zhigh.
    =ZHigh                                            -   NNPA profiling for onnx and zhigh ops.
    =ZLow                                             -   NNPA profiling for zlow ops.

  --instrument-ops=<string>                         - Specify operations operations to be instrumented:
                                                      "NONE" or "" for no instrument,
                                                      "ops1,ops2, ..." for the multiple ops.
                                                      e.g. "onnx.Conv,onnx.Add" for Conv and Add ops.
                                                      Asterisk is also available.
                                                      e.g. "onnx.*" for all onnx operations.

  Specify what instrumentation actions at runtime:
      --InstrumentBeforeOp                          - insert instrument before op,
      --InstrumentAfterOp                           - insert instrument after op,
      --InstrumentReportTime                        - instrument runtime reports time usage,
      --InstrumentReportMemory                      - instrument runtime reports memory usage.

目前，在加载动态库之前需要调用初始化函数 OMInstrumentInit。编译器正在考虑将其添加到 main_graph 的开头。

运行仪器化

像往常一样运行模型。仪器化库将在每个仪器化点输出时间和内存使用情况。例如，一个名为 mymodel.onnx 的模型，使用 onnx-mlir --instrument-stage=Onnx --instrument-ops=onnx.* --InstrumentAfterOp --InstrumentReportMemory --InstrumentReportTime mymodel.onnx 进行编译。其运行时输出如下所示。

==PERF-REPORT==, onnx.Cast, bert/encoder/Reshape__27, before, 0.000001, 1692654182.738546
==PERF-REPORT==, onnx.Cast, bert/encoder/Reshape__27, after, 0.000001, 1692654182.738547
==PERF-REPORT==, onnx.Concat, bert/encoder/Reshape__27, before, 0.000000, 1692654182.738547
==PERF-REPORT==, onnx.Concat, bert/encoder/Reshape__27, after, 0.000001, 1692654182.738548
==PERF-REPORT==, onnx.Reshape, bert/encoder/Reshape, before, 0.000001, 1692654182.738549
==PERF-REPORT==, onnx.Reshape, bert/encoder/Reshape, after, 0.000001, 1692654182.738550

时间测量输出的解释如下。

• 第一列是用于标识正在收集的性能的字符串，这里是 PERF-REPORT。
• 第二列是操作的名称。
• 第三列是操作的节点名称。当操作具有 onnx_node_name 属性时显示此信息。
• 第四列指示所报告的时间是 之前 还是 之后 正在分析的 onnx 操作。
• 第五列指示自上一个仪器化点以来经过的时间。
• 第六列指示自 instrumentationInit 以来的累积时间（秒）。

内存测量输出的解释如下。

• 第一列是用于标识正在收集的性能的字符串，这里是 MEM-REPORT。
• 第二列和第三列的定义如上。
• 第四列表示 VMem，即此进程使用的虚拟内存大小（以 KB 为单位）。

NNPA 的其他示例

• 在降低到 zhigh 操作之前，对 onnx 操作的性能分析： onnx-mlir --march=z16 --maccel=NNPA --instrument-stage=Onnx --instrument-ops=onnx.* --InstrumentBeforeOp --InstrumentAfterOp --InstrumentReportTime mymodel.onnx
• onnx 和 zhigh 操作的性能分析： onnx-mlir --march=z16 --maccel=NNPA --instrument-stage=ZHigh --instrument-ops=onnx.*,zhigh.* --InstrumentBeforeOp --InstrumentAfterOp --InstrumentReportTime mymodel.onnx
• zlow 操作的性能分析： onnx-mlir --march=z16 --maccel=NNPA --instrument-stage=ZLow --instrument-ops=zlow.* --InstrumentBeforeOp --InstrumentAfterOp --InstrumentReportTime mymodel.onnx

在运行时控制仪器化

通过在运行时提供某些环境变量，您可以禁用仪器化库的报告。

• 如果设置了环境变量 ONNX_MLIR_NO_INSTRUMENT，则不产生任何报告。
• 如果设置了环境变量 ONNX_MLIR_NO_INSTRUMENT_TIME，则禁用时间使用情况的报告。
• 如果设置了环境变量 ONNX_MLIR_NO_INSTRUMENT_MEMORY，则禁用内存使用情况的报告。
• 如果设置了环境变量 ONNX_MLIR_INSTRUMENT_FILE，则该变量提供保存仪器化结果的文件名。

请注意，启用仪器化的唯一方法是在编译时请求它。如果在运行时没有启用任何详细报告（例如到目前为止的时间和内存），仪器化点的进度仍会打印出来。此功能被认为有用，作为进度指示器。要完全禁用编译时请求的任何输出，您必须设置 ONNX_MLIR_NO_INSTRUMENT。

在 gdb 中使用

仪器化点的函数名为 OMInstrumentPoint。可以在此函数内部设置断点，以便逐步执行 onnx 操作。