江南人物的博客

CLI11 简介

CLI11 是一个用于处理命令行参数和选项的 C++ 库，旨在简化 C++ 应用程序的命令行界面开发。其主要特点包括：

1. 简单易用：提供直观的 API，使开发者能够轻松定义和解析命令行选项
2. 现代 C++ 支持：充分利用现代 C++ 特性，如类型推导和 lambda 表达式
3. 丰富的选项支持：支持标志选项、位置参数、可选参数和必选参数等
4. 类型安全：在解析和处理命令行参数时提供类型安全的机制
5. 灵活的错误处理：提供多种错误处理方式，包括参数验证失败时的错误提示和帮助信息的自动生成
6. 跨平台支持：可在主流操作系统上运行，包括 Windows、macOS 和各种 Linux 发行版

下载和安装

CLI11 是一个单头文件库，安装非常简单。有以下几种安装方式：

方式一：单文件头文件（推荐）

1. 从 CLI11 GitHub 仓库 下载最新的 CLI11.hpp 文件
2. 将 CLI11.hpp 复制到您的项目包含目录中
3. 在代码中直接包含即可使用：

   1	#include "CLI11.hpp"

方式二：使用 CMake 集成

如果您的项目使用 CMake，可以通过以下方式集成：

1. 作为 Git 子模块：

   1	git submodule add https://github.com/CLIUtils/CLI11.git

   在 CMakeLists.txt 中：

   1 2	add_subdirectory(CLI11) target_link_libraries(your_target CLI11::CLI11)

2. 使用 FetchContent（CMake 3.11+）：

   1 2 3 4 5 6 7 8

   include(FetchContent) FetchContent_Declare( CLI11 GIT_REPOSITORY https://github.com/CLIUtils/CLI11.git GIT_TAG v2.4.1 # 使用最新版本标签 ) FetchContent_MakeAvailable(CLI11) target_link_libraries(your_target CLI11::CLI11)

方式三：包管理器安装

• vcpkg：vcpkg install cli11
• Conan：conan install CLI11/2.4.1@cliutils/stable
• Homebrew（macOS）：brew install cli11

方式四：全局安装

将 CLI11.hpp 复制到系统共享文件夹位置（如 /opt/CLI11 或 /usr/local/include），然后在 CMake 中：

1

include_directories(/opt/CLI11)

注意：CLI11.hpp 包含整个命令行解析库的核心功能。如果需要使用单独的实用工具（如 Timer、AutoTimer），需要单独复制相应的头文件。

CLI11 API 层级关系

CLI11 的核心数据结构

CLI11 有三个核心数据结构：

1. App - 应用根对象

   • 所有选项和子命令的容器
   • 代表整个命令行应用程序
   • Subcommand 实际上就是 App 对象，不是独立的数据结构。
     • add_subcommand() 返回 App*，所以 Subcommand 可以无限嵌套。

2. Option - 选项对象

   • 通过 add_flag() 或 add_option() 创建
   • add_flag() → 返回 Option*
     • 布尔标志，不需要值
     • 示例: app.add_flag("-v", verbose)
   • add_option() → 返回 Option*
     • 需要值的选项
     • 示例: app.add_option("-f", file, "File path")

3. Option_group - 选项组（继承自 App）

   • 继承关系: class Option_group : public App
   • 本质上是 App 对象，可以使用 App 的所有方法
   • 用于组织相关选项
   • 通过 add_option_group() 创建，返回 Option_group*（可转换为 App*）
   • 用于实现 Suboption 功能
   • 嵌套支持: 因为继承自 App，可以在 Option_group 中再创建 Option_group 实现多层嵌套

层级结构

层级 0: App（应用根对象）

1

CLI::App app("description");

• 所有选项和子命令的顶层容器

层级 1: App 的直接子级（三种平级对象）

Option（选项） - 通过 add_flag() 或 add_option() 添加

• add_flag(): 布尔标志，不需要值
• add_option(): 需要值的选项
• 两者都返回 Option*，独立存在

Subcommand（子命令） - 通过 add_subcommand() 添加

• 返回 App* 对象，可以继续调用 add_subcommand() 实现无限嵌套
• 独立存在，本身也是 App 类型

Option_group（选项组） - 通过 add_option_group() 添加

• 返回 Option_group*（继承自 App）
• 用于组织选项，实现 Suboption 功能

层级 2: 依赖关系

Suboption（子选项） - 通过 Option_group + needs() 实现

1
2
3
4

app.add_flag("-add", add_flag);  // 父选项
CLI::Option_group *add_group = app.add_option_group("add_suboptions", "Sub-options for -add");
add_group->add_option("-file", file_path);  // 子选项
add_group->needs(app.get_option("-add"));  // 建立依赖

• 使用: myprog -add -file path.txt（必须先有 -add）
• 多层嵌套: 在 Option_group 中再创建 Option_group

Subcommand 的 Option - 属于 Subcommand

1
2

CLI::App *start = app.add_subcommand("start");
start->add_option("-f", file_path);  // 子命令的选项

• 使用: myprog start -f file.txt

关键区别

一个 Suboption 的示例程序

以下是一个 Suboption 的示例程序，不支持子命令，使用单横线作为长选项，支持子选项。
我们选择这个示例是因为 Subcommand 的实现比较简单（就是 App 的无限嵌套），所以我们写了一个支持子选项的示例程序来演示更复杂的用法。

示例程序的层级结构

示例程序演示了三级层级结构：

1
2
3
4
5
6
7
8
9
10

App (myprog)
├── Option (-add)          ← Level 1: 顶级选项 (flag)
├── Option (-del)          ← Level 1: 顶级选项 (flag, 与 -add 平级)
├── Option (-force)        ← Level 1: 顶级选项 (flag, 与 -add 平级)
└── Option_group (add_suboptions)  ← Level 2: 子选项组
    ├── Option (-file)     ← Level 2: -add 的子选项 (需要值)
    ├── Option (-recursive)← Level 2: -add 的子选项 (flag, 不需要值)
    └── Option_group (file_suboptions)  ← Level 3: -file 的子选项组
        ├── Option (-encoding)   ← Level 3: -file 的子选项 (需要值)
        └── Option (-overwrite)  ← Level 3: -file 的子选项 (flag, 不需要值)

依赖关系通过以下方式建立：

• add_group->needs(add_option) - 使选项组要求 -add 选项必须存在
• file_group->needs(file_option) - 使文件子选项组要求 -file 选项必须存在

示例命令行：

• 仅 Level 1: myprog -add -del -force
• Level 1 + 2: myprog -add -file path/to/file.txt -recursive -del -force
• Level 1 + 2 + 3: myprog -add -file path/to/file.txt -encoding utf8 -overwrite -del -force

文件说明

suboption_example.cpp - 示例程序

suboption_example.cpp 是一个可执行的示例程序，用于演示子选项功能。可以直接运行并测试功能。

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

// Copyright (c) 2017-2025, University of Cincinnati, developed by Henry Schreiner
// under NSF AWARD 1414736 and by the respective contributors.
// All rights reserved.
//
// SPDX-License-Identifier: BSD-3-Clause

// 示例程序：演示子选项功能（三级层级）
// 编译: g++ -std=c++11 example.cpp -I../../include -o example
// 运行示例:
//   ./example -add -file path/to/file.txt -recursive -del -force
//   ./example -add -file path/to/file.txt -encoding utf8 -overwrite -del -force

#ifdef CLI11_SINGLE_FILE
#include "CLI11.hpp"
#else
#include "CLI/CLI.hpp"
#endif

#include <iostream>
#include <string>

int main(int argc, char **argv) {
    CLI::App app{"SubOption Example Program"};

    bool add_flag = false;
    bool del_flag = false;
    bool force_flag = false;
    std::string file_path;        // Level 2: 需要值的选项
    bool recursive_flag = false;  // Level 2: 标志选项
    std::string encoding;         // Level 3: 需要值的选项
    bool overwrite_flag = false;  // Level 3: 标志选项

    // 允许非标准选项名（单破折号后面跟多个字符）
    app.allow_non_standard_option_names();

    // 平级选项：-add, -del, -force
    app.add_flag("-add", add_flag, "Add option");
    app.add_flag("-del", del_flag, "Delete option");
    app.add_flag("-force", force_flag, "Force option");

    // -add 的子选项：-file (需要值) 和 -recursive (标志)
    // 使用选项组来实现子选项功能
    CLI::Option_group *add_group = app.add_option_group("add_suboptions", "Sub-options for -add");
    add_group->allow_non_standard_option_names();  // 选项组也需要启用非标准选项名
    add_group->add_option("-file", file_path, "File path (requires a value)");
    add_group->add_flag("-recursive", recursive_flag, "Process recursively (flag, no value needed)");

    // 子选项需要 -add 选项存在
    CLI::Option *add_option = app.get_option("-add");
    add_group->needs(add_option);

    // 第三级层级：-file 的子选项
    // 在 -file 选项组下再创建一个选项组
    CLI::Option_group *file_group = add_group->add_option_group("file_suboptions", "Sub-options for -file");
    file_group->allow_non_standard_option_names();
    file_group->add_option("-encoding", encoding, "File encoding (requires a value, e.g., utf8, gbk)");
    file_group->add_flag("-overwrite", overwrite_flag, "Overwrite existing file (flag, no value needed)");
    
    // 子子选项需要 -file 选项存在
    auto *file_option = add_group->get_option("-file");
    file_group->needs(file_option);

    // 解析命令行参数
    try {
        app.parse(argc, argv);
    } catch(const CLI::ParseError &e) {
        return app.exit(e);
    }

    // 输出结果
    std::cout << "解析结果:\n";
    std::cout << "  -add: " << (add_flag ? "true" : "false") << "\n";
    std::cout << "  -del: " << (del_flag ? "true" : "false") << "\n";
    std::cout << "  -force: " << (force_flag ? "true" : "false") << "\n";
    
    if(add_flag) {
        std::cout << "  -file: " << (file_path.empty() ? "(未设置)" : file_path) << "\n";
        std::cout << "  -recursive: " << (recursive_flag ? "true" : "false") << "\n";
        
        if(!file_path.empty()) {
            std::cout << "    -encoding: " << (encoding.empty() ? "(未设置)" : encoding) << "\n";
            std::cout << "    -overwrite: " << (overwrite_flag ? "true" : "false") << "\n";
        }
    }

    return 0;
}

构建和运行示例程序

1
2
3
4
5
6

cd /home/zhigaoz/code/CLI11/build
cmake --build . --target suboption_example
# Run examples
./tests/suboption_test/suboption_example --help
./tests/suboption_test/suboption_example -add
./tests/suboption_test/suboption_example -add -file path/to/file.txt -encoding utf8 -overwrite -del -force

实现细节

测试使用 CLI11 的 Option_group 功能和 needs() 方法，确保子选项只有在父选项存在时才有效。

关键实现细节

1. 非标准选项名:

   • 使用 app.allow_non_standard_option_names() 允许单破折号后面跟多个字符的选项（例如 -add 而不是 --add）

2. 选项组创建:

   1 2	CLI::Option_group *file_group = add_group->add_option_group("file_suboptions", "Sub-options for -file"); file_group->allow_non_standard_option_names();

3. 依赖关系:

   1 2	CLI::Option *add_option = app.get_option("-add"); add_group->needs(add_option); // 子选项需要 -add 选项存在

4. 添加子选项:

   1 2 3 4

   // 注意：CLI11 没有 add_suboption() 函数 // 子选项通过在 Option_group 中使用 add_option() 或 add_flag() 实现 add_group->add_option("-file", file_path, "File path (requires a value)"); add_group->add_flag("-recursive", recursive_flag, "Process recursively (flag, no value needed)");

引言

InfiniBand/RDMA 提供了两种截然不同的数据传输模式：Send/Recv 和 Read/Write。这两种模式在底层实现机制、CPU 参与度、对端感知性和传输控制策略方面存在根本性差异。

核心差异对比

基本特性对比

工作机制对比

CPU 参与度与对端感知性

传输速率控制

RNR 机制参数：

1
2
3

// 在 modify_qp_to_rts 中设置
attr.rnr_retry = 7;          // RNR 重试次数
attr.min_rnr_timer = 0x12;   // 最小 RNR 等待时间

API 与代码示例

关键函数

ibv_post_recv()

接收端必须预先调用此函数提交 Receive WR：

1
2
3
4
5

#include <infiniband/verbs.h>

int ibv_post_recv(struct ibv_qp *qp, 
                  struct ibv_recv_wr *wr,
                  struct ibv_recv_wr **bad_wr);

返回值：成功返回 0，失败返回错误码

ibv_post_send()

发送端调用此函数提交 Send WR 或 RDMA Read/Write WR：

1
2
3

int ibv_post_send(struct ibv_qp *qp,
                  struct ibv_send_wr *wr,
                  struct ibv_send_wr **bad_wr);

数据结构

Receive Work Request

1
2
3
4
5
6

struct ibv_recv_wr {
    uint64_t                wr_id;      // 工作请求标识符
    struct ibv_recv_wr     *next;       // 下一个 WR（可组成链表）
    struct ibv_sge         *sg_list;    // Scatter/Gather 元素数组
    int                     num_sge;    // SGE 数量
};

Send Work Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

struct ibv_send_wr {
    uint64_t                wr_id;           // 工作请求标识符
    struct ibv_send_wr     *next;            // 下一个 WR
    struct ibv_sge         *sg_list;         // Scatter/Gather 元素数组
    int                     num_sge;         // SGE 数量
    enum ibv_wr_opcode      opcode;          // 操作类型
    int                     send_flags;      // 发送标志
    union {
        struct {
            uint64_t        remote_addr;     // 远程地址（RDMA 操作使用）
            uint32_t        rkey;            // 远程密钥（RDMA 操作使用）
        } rdma;
        // ... 其他操作类型
    } wr;
    uint32_t                imm_data;        // 立即数据（可选）
};

Scatter/Gather Element

1
2
3
4
5

struct ibv_sge {
    uint64_t        addr;    // 缓冲区地址
    uint32_t        length;  // 缓冲区长度
    uint32_t        lkey;    // 本地内存区域密钥
};

操作码与标志位

Send/Recv 代码示例

接收端代码

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

// 1. 准备接收缓冲区
char *recv_buffer = malloc(BUFFER_SIZE);
struct ibv_mr *recv_mr = ibv_reg_mr(pd, recv_buffer, BUFFER_SIZE,
                                    IBV_ACCESS_LOCAL_WRITE);

// 2. 准备 Scatter/Gather Element
struct ibv_sge recv_sge;
recv_sge.addr = (uintptr_t)recv_buffer;
recv_sge.length = BUFFER_SIZE;
recv_sge.lkey = recv_mr->lkey;

// 3. 准备 Receive Work Request
struct ibv_recv_wr recv_wr, *bad_recv_wr;
memset(&recv_wr, 0, sizeof(recv_wr));
recv_wr.wr_id = (uintptr_t)recv_buffer;
recv_wr.sg_list = &recv_sge;
recv_wr.num_sge = 1;

// 4. 提交 Receive WR（必须预先提交）
if (ibv_post_recv(qp, &recv_wr, &bad_recv_wr)) {
    fprintf(stderr, "Failed to post receive WR\n");
    return -1;
}

// 5. 等待接收完成
struct ibv_wc wc;
int ne;
do {
    ne = ibv_poll_cq(cq, 1, &wc);
} while (ne == 0);

if (wc.status != IBV_WC_SUCCESS) {
    fprintf(stderr, "Receive failed with status: %s\n",
            ibv_wc_status_str(wc.status));
    return -1;
}

发送端代码

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

// 1. 准备发送缓冲区
char *send_buffer = malloc(BUFFER_SIZE);
memcpy(send_buffer, data_to_send, data_size);
struct ibv_mr *send_mr = ibv_reg_mr(pd, send_buffer, BUFFER_SIZE,
                                     IBV_ACCESS_LOCAL_WRITE);

// 2. 准备 Scatter/Gather Element
struct ibv_sge send_sge;
send_sge.addr = (uintptr_t)send_buffer;
send_sge.length = data_size;
send_sge.lkey = send_mr->lkey;

// 3. 准备 Send Work Request
struct ibv_send_wr send_wr, *bad_send_wr;
memset(&send_wr, 0, sizeof(send_wr));
send_wr.wr_id = (uintptr_t)send_buffer;
send_wr.opcode = IBV_WR_SEND;              // Send/Recv 模式
send_wr.send_flags = IBV_SEND_SIGNALED;    // 请求完成通知
send_wr.sg_list = &send_sge;
send_wr.num_sge = 1;

// 4. 提交 Send WR
if (ibv_post_send(qp, &send_wr, &bad_send_wr)) {
    fprintf(stderr, "Failed to post send WR\n");
    return -1;
}

// 5. 等待发送完成
struct ibv_wc wc;
int ne;
do {
    ne = ibv_poll_cq(cq, 1, &wc);
} while (ne == 0);

Read/Write 代码示例

RDMA Write 操作

1
2
3
4
5
6
7
8
9
10
11
12
13

// 发起端代码
struct ibv_send_wr write_wr, *bad_wr;
memset(&write_wr, 0, sizeof(write_wr));

write_wr.wr_id = (uintptr_t)local_buffer;
write_wr.opcode = IBV_WR_RDMA_WRITE;        // RDMA Write
write_wr.send_flags = IBV_SEND_SIGNALED;
write_wr.sg_list = &sge;
write_wr.num_sge = 1;
write_wr.wr.rdma.remote_addr = remote_addr;  // 远程内存地址
write_wr.wr.rdma.rkey = remote_rkey;         // 远程内存密钥

ibv_post_send(qp, &write_wr, &bad_wr);

RDMA Read 操作

1
2
3
4
5
6
7
8
9
10
11
12

struct ibv_send_wr read_wr, *bad_wr;
memset(&read_wr, 0, sizeof(read_wr));

read_wr.wr_id = (uintptr_t)local_buffer;
read_wr.opcode = IBV_WR_RDMA_READ;          // RDMA Read
read_wr.send_flags = IBV_SEND_SIGNALED;
read_wr.sg_list = &sge;
read_wr.num_sge = 1;
read_wr.wr.rdma.remote_addr = remote_addr;  // 远程内存地址
read_wr.wr.rdma.rkey = remote_rkey;         // 远程内存密钥

ibv_post_send(qp, &read_wr, &bad_wr);

内存注册要求

1
2
3
4
5
6
7
8
9

// 对端注册内存（允许远程访问）
struct ibv_mr *remote_mr = ibv_reg_mr(pd, remote_buffer, BUFFER_SIZE,
                                       IBV_ACCESS_LOCAL_WRITE |      // 本地写权限
                                       IBV_ACCESS_REMOTE_READ |      // 允许远程读
                                       IBV_ACCESS_REMOTE_WRITE);     // 允许远程写

// 将 R_Key 和地址传递给发起端
// remote_addr = (uint64_t)remote_buffer;
// remote_rkey = remote_mr->rkey;

同步机制

Send/Recv 同步机制

关键问题：ibv_post_recv 必须在 ibv_post_send 之前吗？

答案：不是必须在 ibv_post_send 之前调用，但必须在数据到达之前 post recv。

调用顺序说明

工作原理

1. 接收队列（RQ）机制：

   • 接收端调用 ibv_post_recv() 将 Receive WR 提交到接收队列（RQ）
   • 当数据包到达时，HCA 硬件从 RQ 中取出一个 Receive WR
   • 如果 RQ 中没有 Receive WR，HCA 返回 RNR（Receiver Not Ready）NACK

2. 时序要求：

   • 不是要求 ibv_post_recv() 必须在 ibv_post_send() 之前调用
   • 而是要求数据包到达时，RQ 中必须有可用的 Receive WR
   • 由于网络延迟，通常可以预先 post recv

代码示例

场景 1：预先批量 post recv（推荐）

1
2
3
4
5
6
7
8
9
10

// 接收端：预先批量提交多个 Receive WR
for (int i = 0; i < BATCH_SIZE; i++) {
    struct ibv_recv_wr recv_wr, *bad_wr;
    // ... 准备 recv_wr
    ibv_post_recv(qp, &recv_wr, &bad_wr);
}

// 此时发送端可以随时 post send
// 发送端：随时发送数据
ibv_post_send(qp, &send_wr, &bad_send_wr);

场景 2：RNR 错误处理

1
2
3
4
5
6
7
8
9
10
11

// 发送端处理 RNR 错误
struct ibv_wc wc;
ibv_poll_cq(cq, 1, &wc);

if (wc.status == IBV_WC_RNR_RETRY_EXC_ERR) {
    // RNR 重试次数超限
    fprintf(stderr, "RNR retry exceeded\n");
} else if (wc.status == IBV_WC_REM_OP_ERR) {
    // 可能是 RNR 错误
    fprintf(stderr, "Remote operation error, possibly RNR\n");
}

最佳实践

Read/Write 同步机制

由于 Read/Write 操作对端无感知，需要额外的同步机制来保证数据一致性和操作顺序。

同步问题

同步机制对比

RDMA Write with Immediate

在写入数据的同时，发送立即数据通知对端：

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

// 发起端：写入数据并通知
struct ibv_send_wr write_wr, *bad_wr;
memset(&write_wr, 0, sizeof(write_wr));

write_wr.wr_id = (uintptr_t)local_buffer;
write_wr.opcode = IBV_WR_RDMA_WRITE_WITH_IMM;  // 带立即数据的 Write
write_wr.send_flags = IBV_SEND_SIGNALED;
write_wr.sg_list = &sge;
write_wr.num_sge = 1;
write_wr.wr.rdma.remote_addr = remote_addr;
write_wr.wr.rdma.rkey = remote_rkey;
write_wr.imm_data = htonl(NOTIFICATION_FLAG);  // 立即数据（网络字节序）

ibv_post_send(qp, &write_wr, &bad_wr);

// 对端：接收立即数据通知（需要预先 post recv）
struct ibv_recv_wr recv_wr, *bad_recv_wr;
// ... 准备 Receive WR
ibv_post_recv(qp, &recv_wr, &bad_recv_wr);

// 轮询 CQ，接收立即数据通知
struct ibv_wc wc;
ibv_poll_cq(cq, 1, &wc);
if (wc.opcode == IBV_WC_RECV_RDMA_WITH_IMM) {
    uint32_t imm_data = ntohl(wc.imm_data);
    // 知道数据已经写入，可以安全读取
}

内存屏障（Fence）机制

使用 IBV_SEND_FENCE 保证操作顺序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// 场景：需要保证多个 RDMA Write 的顺序
struct ibv_send_wr wr[3], *bad_wr;

// WR 1: 写入元数据
wr[0].opcode = IBV_WR_RDMA_WRITE;
wr[0].send_flags = 0;
wr[0].next = &wr[1];

// WR 2: Fence，确保前面的操作完成
wr[1].opcode = IBV_WR_RDMA_WRITE;
wr[1].send_flags = IBV_SEND_FENCE;  // 栅栏标志
wr[1].next = &wr[2];

// WR 3: 写入标志位（表示数据已准备好）
wr[2].opcode = IBV_WR_RDMA_WRITE;
wr[2].send_flags = IBV_SEND_SIGNALED;
wr[2].next = NULL;

ibv_post_send(qp, &wr[0], &bad_wr);
// 保证：元数据写入 → Fence → 标志位写入（顺序执行）

Fence 的作用：

• 确保 Fence 之前的所有操作在 Fence 之后的操作之前完成
• 保证操作的全局顺序（跨多个 QP）
• 适用于需要严格顺序的场景

原子操作同步

使用原子操作作为同步点：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// 对端：准备数据后，使用原子操作设置标志
struct ibv_send_wr atomic_wr, *bad_wr;
memset(&atomic_wr, 0, sizeof(atomic_wr));

// 关键操作码：Compare and Swap 原子操作
// 作用：原子地比较远程内存的值，如果等于期望值则交换为新值
// 特点：这是硬件保证的原子操作，不会被其他操作打断，用于实现同步原语
atomic_wr.opcode = IBV_WR_ATOMIC_CMP_AND_SWP;

// 关键标志位：请求完成通知
// 作用：操作完成后在 CQ 中生成完成事件，用于确认原子操作是否成功
// 注意：原子操作的成功/失败通过 Work Completion 的状态字段判断
atomic_wr.send_flags = IBV_SEND_SIGNALED;
atomic_wr.sg_list = &sge;  // 本地缓冲区，用于存储旧值
atomic_wr.num_sge = 1;
atomic_wr.wr.atomic.remote_addr = remote_flag_addr;  // 远程标志位地址
atomic_wr.wr.atomic.rkey = remote_rkey;
atomic_wr.wr.atomic.compare_add = 0;      // 期望值：0（未准备好）
atomic_wr.wr.atomic.swap = 1;              // 新值：1（已准备好）

ibv_post_send(qp, &atomic_wr, &bad_wr);

Read 时的并发安全

问题：如果 Read 时对端 CPU 正在修改数据，可能导致读取到不一致的数据。

解决方案：

版本号机制：

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

// 数据结构
struct data_with_version {
    uint64_t version;      // 版本号
    char data[BUFFER_SIZE]; // 实际数据
};

// 对端：修改数据时增加版本号
void update_data(struct data_with_version *buf) {
    prepare_new_data(buf->data);
    __sync_synchronize();  // 内存屏障
    __sync_add_and_fetch(&buf->version, 1);  // 原子增加版本号
}

// 发起端：读取时检查版本号
uint64_t old_version = 0;
do {
    uint64_t version_before = read_version();
    __sync_synchronize();
    read_data(buffer);
    __sync_synchronize();
    uint64_t version_after = read_version();
    
    // 如果版本号相同，说明读取期间数据未变化
    if (version_before == version_after && version_before != old_version) {
        break;  // 数据一致，可以使用
    }
    old_version = version_before;
} while (1);

双缓冲机制：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// 对端：使用两个缓冲区交替
struct double_buffer {
    char buffer[2][BUFFER_SIZE];
    volatile int active_index;  // 当前活跃缓冲区索引
};

// 对端：修改数据
void update_data(struct double_buffer *db) {
    int write_index = 1 - db->active_index;  // 写入非活跃缓冲区
    prepare_data(db->buffer[write_index]);
    __sync_synchronize();
    __sync_lock_test_and_set(&db->active_index, write_index);  // 切换缓冲区
}

// 发起端：读取数据
void read_data(struct double_buffer *db) {
    int read_index = db->active_index;  // 读取当前活跃缓冲区
    rdma_read(db->buffer[read_index]);   // RDMA Read
    // 即使对端切换缓冲区，读取的也是完整的数据
}

同步机制选择建议

应用与实践

应用场景对比

混合使用策略

在实际应用中，可以混合使用两种模式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// 示例：使用 Send/Recv 进行控制，使用 Write 进行数据传输

// 1. 通过 Send/Recv 交换元数据
struct metadata {
    uint64_t data_addr;
    uint32_t data_rkey;
    size_t data_size;
} meta;
send_metadata(&meta);

// 2. 通过 RDMA Write 传输实际数据
rdma_write_data(meta.data_addr, meta.data_rkey, data_buffer, meta.data_size);

// 3. 通过 Send/Recv 发送完成通知
send_completion_notification();

性能优化

Send/Recv 性能优化代码：

1
2
3
4
5
6
7
8
9

// 1. 批量提交 Receive WR
for (int i = 0; i < BATCH_SIZE; i++) {
    post_recv_wr();
}

// 2. 周期性 Signaling
if (count % 64 == 0) {
    send_wr.send_flags |= IBV_SEND_SIGNALED;
}

Read/Write 性能优化代码：

1
2
3
4
5
6
7
8
9

// 1. 批量操作
struct ibv_send_wr *wr_list = build_wr_list();
ibv_post_send(qp, wr_list, &bad_wr);

// 2. 避免频繁 Signaling
write_wr.send_flags = 0;  // 不请求完成通知

// 3. 内存对齐
posix_memalign((void**)&buffer, 64, size);  // 64 字节对齐

注意事项

总结

Send/Recv 和 Read/Write 代表了 InfiniBand/RDMA 的两种不同设计哲学：

在实际应用中，应根据具体场景的需求，灵活选择或组合使用这两种模式，充分发挥 InfiniBand/RDMA 的性能优势。

概述

InfiniBand 是一种高性能计算机网络通信标准，具有极高的吞吐量和极低的延迟。本文介绍 InfiniBand/RDMA 编程中的关键概念及其相互关系。

核心概念

1. CA (Channel Adapter) - 通道适配器

CA 是 InfiniBand 网络接口卡（NIC），是硬件层面的概念。每个 CA 都有一个或多个端口（Port），用于连接到 InfiniBand 网络。

2. PD (Protection Domain) - 保护域

保护域是一个安全边界，用于将 QP（队列对）和 MR（内存区域）组织在一起。只有属于同一个 PD 的 QP 和 MR 才能相互操作，这提供了内存保护机制。

3. MR (Memory Region) - 内存区域

内存区域是一块经过注册的内存，网卡可以直接访问。每个 MR 包含：

• L_Key (Local Key): 本地访问密钥，用于本地 QP 访问本地 MR
• R_Key (Remote Key): 远程访问密钥，用于远程 QP 访问此 MR（通过 RDMA 操作）

4. QP (Queue Pair) - 队列对

队列对是 InfiniBand 通信的基本单位，由两个队列组成：

• SQ (Send Queue): 发送队列，用于发送数据
• RQ (Receive Queue): 接收队列，用于接收数据

每个 QP 必须属于一个 PD，并且可以关联多个 CQ。

5. CQ (Completion Queue) - 完成队列

完成队列用于接收工作请求（WR）的完成通知。当 WR 执行完成后，会在对应的 CQ 中生成一个完成事件（Completion Event）。

6. WR (Work Request) - 工作请求

工作请求是提交到 QP 的操作指令，包括：

• Send WR: 发送请求
• Receive WR: 接收请求
• RDMA Write WR: RDMA 写请求
• RDMA Read WR: RDMA 读请求

7. SGE (Scatter/Gather Elements) - 分散/聚集元素

SGE 描述了一个内存缓冲区的位置和大小，包含：

• 地址（Address）
• 长度（Length）
• L_Key（用于验证访问权限）

一个 WR 可以包含多个 SGE，实现分散/聚集 I/O。

注: SGE 专门用于描述本地散布的缓冲区, 即散布读写(Scatter read/write), 类似于 Linux 的 writev / readv 函数.

8. LID (Local Identifier) - 本地标识符

LID 是 InfiniBand 网络中每个端口的唯一标识符，用于路由数据包。

9. AH (Address Handle) - 地址句柄

地址句柄用于 UD (Unreliable Datagram) 传输类型，包含目标地址信息。每个 AH 属于一个 PD，用于在 UD QP 发送数据时指定目标地址。AH 包含：

• 目标 LID (Local Identifier)
• 服务级别 (Service Level)
• 路径位 (Path Bits)
• 全局路由头 (GRH) 信息（如果使用）

10. CM (Connection Manager) - 连接管理器

连接管理器负责建立和管理 QP 之间的连接，处理连接建立、断开等事件。

保护域（PD）资源组织结构图

以下 ASCII 图详细说明了 PD（保护域）内资源的结构和关系：

重要说明：图中 CQ 显示在 PD 内是为了展示逻辑关联关系。实际上：

• CQ 通过 Context 创建（ibv_create_cq()），不属于任何 PD
• CQ 是 Context 级别的资源，可以被不同 PD 的 QP 共享
• 多个 QP（即使属于不同的 PD）可以关联到同一个 CQ
• 例如：PD 1 的 QP 1、QP 2 和 PD 2 的 QP 3、QP 4 可以共享同一个 CQ

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

┌─────────────────────────────────────────────────────────────────────┐
│                      Application Process                           │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              │ ibv_open_device()
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Context                                     │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              │ ibv_alloc_pd()
                              ▼
        ┌─────────────────────────────────────────────────────────┐
        │                                                         │
        ▼                                                         ▼
┌──────────────────────────────────────┐    ┌──────────────────────────────────────┐
│         PD 1 (Protection Domain)     │    │         PD 2 (Protection Domain)     │
│                                      │    │                                      │
│  Resources in PD 1:                  │    │  Resources in PD 2:                 │
│                                      │    │                                      │
│  ┌────────────────────────────────┐  │    │  ┌────────────────────────────────┐  │
│  │  MR 1                          │  │    │  │  MR 3                          │  │
│  │  L_Key: 0x01  R_Key: 0x81      │  │    │  │  L_Key: 0x05  R_Key: 0x85     │  │
│  └────────────────────────────────┘  │    │  └────────────────────────────────┘  │
│                                      │    │                                      │
│  ┌────────────────────────────────┐  │    │  ┌────────────────────────────────┐  │
│  │  MR 2                          │  │    │  │  MR 4                          │  │
│  │  L_Key: 0x02  R_Key: 0x82      │  │    │  │  L_Key: 0x06  R_Key: 0x86     │  │
│  └────────────────────────────────┘  │    │  └────────────────────────────────┘  │
│                                      │    │                                      │
│  ┌────────────────────────────────┐  │    │  ┌────────────────────────────────┐  │
│  │  AH 1                          │  │    │  │  AH 3                          │  │
│  │  Target LID, Service Level     │  │    │  │  Target LID, Service Level     │  │
│  └────────────────────────────────┘  │    │  └────────────────────────────────┘  │
│                                      │    │                                      │
│  ┌────────────────────────────────┐  │    │  ┌────────────────────────────────┐  │
│  │  AH 2                          │  │    │  │  AH 4                          │  │
│  │  Target LID, Service Level     │  │    │  │  Target LID, Service Level     │  │
│  └────────────────────────────────┘  │    │  └────────────────────────────────┘  │
│                                      │    │                                      │
│  ┌────────────────────────────────┐  │    │  ┌────────────────────────────────┐  │
│  │  QP 1                          │  │    │  │  QP 3                          │  │
│  │  Uses: MR 1/2, AH 1/2, CQ 1    │  │    │  │  Uses: MR 3/4, AH 3/4, CQ 1/2  │  │
│  └────────────────────────────────┘  │    │  └────────────────────────────────┘  │
│                                      │    │                                      │
│  ┌────────────────────────────────┐  │    │  ┌────────────────────────────────┐  │
│  │  QP 2                          │  │    │  │  QP 4                          │  │
│  │  Uses: MR 1/2, AH 1/2, CQ 1    │  │    │  │  Uses: MR 3/4, AH 3/4, CQ 1/2  │  │
│  └────────────────────────────────┘  │    │  └────────────────────────────────┘  │
│                                      │    │                                      │
└──────────────────────────────────────┘    └──────────────────────────────────────┘
        │                                                         │
        │  Security Boundary                                      │  Security Boundary
        └─────────────────────────────────────────────────────────┘
                              │
                              │
                              ▼
┌───────────────────────────────────────────────────────────────────┐
│  CQ (Created via Context, NOT belonging to any PD)                │
│  CQ can be shared by QP from different PDs!                       │
│                                                                   │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  CQ 1 (Shared across PDs)                                    │ │
│  │  Receives completions from:                                  │ │
│  │    - QP 1 (PD 1)                                             │ │
│  │    - QP 2 (PD 1)                                             │ │
│  │    - QP 3 (PD 2)  ← Cross-PD sharing                         │ │
│  │    - QP 4 (PD 2)  ← Cross-PD sharing                         │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  CQ 2 (Alternative: separate CQ for PD 2)                    │ │
│  │  Receives completions from:                                  │ │
│  │    - QP 3 (PD 2)                                             │ │
│  │    - QP 4 (PD 2)                                             │ │
│  └──────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘
                              │
                              │ Hardware Access
                              ▼
                    ┌──────────────────┐
                    │  CA (NIC)        │
                    └──────────────────┘

资源使用关系：
─────────────────────────────
QP 1 (PD 1) ──使用──> MR 1, MR 2, AH 1, AH 2
QP 1 (PD 1) ──发送完成事件到──> CQ 1

QP 2 (PD 1) ──使用──> MR 1, MR 2, AH 1, AH 2
QP 2 (PD 1) ──发送完成事件到──> CQ 1

QP 3 (PD 2) ──使用──> MR 3, MR 4, AH 3, AH 4
QP 3 (PD 2) ──发送完成事件到──> CQ 1 (共享) 或 CQ 2

QP 4 (PD 2) ──使用──> MR 3, MR 4, AH 3, AH 4
QP 4 (PD 2) ──发送完成事件到──> CQ 1 (共享) 或 CQ 2

关键点：CQ 可以被不同 PD 的 QP 共享！

关键关系说明：
═══════════════════════════════════════════════════════════════════

1. PD 作为安全边界
   ─────────────────
   • PD 1 和 PD 2 相互隔离，互不干扰
   • PD 直接管理的资源：MR、QP、AH
   • CQ 通过 Context 创建，通过 QP 间接关联到 PD（QP 创建时指定 CQ）
   • 只有属于同一个 PD 的 QP 和 MR 才能相互操作
   • PD 提供了内存和队列的访问控制机制

2. MR (Memory Region) - 内存区域
   ──────────────────────────────
   • MR 1 和 MR 2 属于 PD 1
   • MR 3 和 MR 4 属于 PD 2
   • 每个 MR 都有唯一的 L_Key（本地密钥）和 R_Key（远程密钥）
   • MR 是 QP 可以访问的内存区域

3. QP (Queue Pair) - 队列对
   ──────────────────────────
   • QP 1 和 QP 2 属于 PD 1
   • QP 3 和 QP 4 属于 PD 2
   • 每个 QP 包含：
     - SQ (Send Queue): 发送队列，用于发送数据
     - RQ (Receive Queue): 接收队列，用于接收数据
   • QP 只能访问同一 PD 内的 MR

4. CQ (Completion Queue) - 完成队列
   ──────────────────────────────────
   • CQ 通过 Context 创建（`ibv_create_cq()`），不属于任何 PD
   • CQ 是 Context 级别的资源，可以被不同 PD 的 QP 共享
   • 多个 QP（即使属于不同的 PD）可以关联到同一个 CQ
   • 示例：
     - CQ 1 可以同时接收 PD 1 的 QP 1、QP 2 和 PD 2 的 QP 3、QP 4 的完成事件
     - 这种设计提供了灵活性，允许跨 PD 共享完成队列
   • 注意：虽然图中 CQ 显示在 PD 内，但这是逻辑关联，CQ 本身不属于 PD

   QP 如何将完成事件发送到 CQ：
   ────────────────────────────────
   1. QP 创建时关联 CQ：
      - 创建 QP 时，在 `ibv_qp_init_attr` 中指定 `send_cq` 和 `recv_cq`
      - 每个 QP 可以有不同的 send_cq 和 recv_cq，也可以使用同一个 CQ
   
   2. WR 标志控制完成事件生成：
      - Send WR：设置 `IBV_SEND_SIGNALED` 标志，完成后在 send_cq 中生成 CQE
      - Receive WR：总是生成完成事件（在 recv_cq 中生成 CQE）
      - 未设置 SIGNALED 的 Send WR 不会生成完成事件
   
   3. 硬件自动生成完成事件：
      - 当 WR 执行完成后，硬件（CA）自动在对应的 CQ 中生成 CQE（Completion Queue Entry）
      - CQE 包含：状态码、操作类型、WR ID、字节数等信息
      - 应用程序通过 `ibv_poll_cq()` 轮询 CQ 获取完成事件
   
   4. 完成事件流程：
      Application → ibv_post_send/recv() → QP (SQ/RQ)
                                                      ↓
                                              WR 执行完成
                                                      ↓
                                             硬件生成 CQE
                                                      ↓
                                             写入到 CQ
                                                      ↓
                                      Application ← ibv_poll_cq()

5. AH (Address Handle) - 地址句柄
   ────────────────────────────────
   • AH 1 和 AH 2 属于 PD 1
   • AH 3 和 AH 4 属于 PD 2
   • AH 主要用于 UD (Unreliable Datagram) 传输类型
   • UD QP 发送数据时，WR 必须包含 AH 来指定目标地址
   • AH 包含目标 LID、服务级别等路由信息

6. WR (Work Request) - 工作请求
   ──────────────────────────────
   • WR 提交到 QP 的 SQ 或 RQ
   • WR 包含一个或多个 SGE（Scatter/Gather Elements）
   • SGE 引用 MR，使用 L_Key 验证访问权限
   • UD QP 的 Send WR 必须包含 AH 来指定目标地址

7. 访问规则
   ─────────
   ✅ 允许：QP 1 → MR 1 (同一 PD)
   ✅ 允许：QP 1 → MR 2 (同一 PD)
   ✅ 允许：QP 2 → MR 1 (同一 PD)
   ✅ 允许：QP 2 → MR 2 (同一 PD)
   ✅ 允许：QP 3 → MR 3 (同一 PD)
   ✅ 允许：QP 3 → MR 4 (同一 PD)
   ✅ 允许：QP 4 → MR 3 (同一 PD)
   ✅ 允许：QP 4 → MR 4 (同一 PD)
   ✅ 允许：QP 1 → CQ 1 (CQ 可以被不同 PD 共享)
   ✅ 允许：QP 2 → CQ 1 (CQ 可以被不同 PD 共享)
   ✅ 允许：QP 3 → CQ 1 (CQ 可以被不同 PD 共享，跨 PD)
   ✅ 允许：QP 3 → CQ 2 (CQ 可以被不同 PD 共享)
   ✅ 允许：QP 4 → CQ 1 (CQ 可以被不同 PD 共享，跨 PD)
   ✅ 允许：QP 4 → CQ 2 (CQ 可以被不同 PD 共享)
   ✅ 允许：QP 1 → AH 1 (同一 PD，UD QP)
   ✅ 允许：QP 1 → AH 2 (同一 PD，UD QP)
   ✅ 允许：QP 2 → AH 1 (同一 PD，UD QP)
   ✅ 允许：QP 2 → AH 2 (同一 PD，UD QP)
   ✅ 允许：QP 3 → AH 3 (同一 PD，UD QP)
   ✅ 允许：QP 3 → AH 4 (同一 PD，UD QP)
   ✅ 允许：QP 4 → AH 3 (同一 PD，UD QP)
   ✅ 允许：QP 4 → AH 4 (同一 PD，UD QP)
   ❌ 禁止：QP 1 → MR 3 (不同 PD)
   ❌ 禁止：QP 1 → MR 4 (不同 PD)
   ❌ 禁止：QP 3 → MR 1 (不同 PD)
   ❌ 禁止：QP 3 → MR 2 (不同 PD)
   ❌ 禁止：QP 1 → AH 3 (不同 PD)
   ❌ 禁止：QP 1 → AH 4 (不同 PD)
   ❌ 禁止：QP 3 → AH 1 (不同 PD)
   ❌ 禁止：QP 3 → AH 2 (不同 PD)

8. 内存保护机制
   ──────────────
   • L_Key: 用于本地 QP 访问本地 MR
     - QP 1 使用 L_Key 0x01 访问 MR 1
     - QP 1 使用 L_Key 0x02 访问 MR 2
     - SGE 中必须包含正确的 L_Key 才能访问 MR
   
   • R_Key: 用于远程 RDMA 操作
     - 远程 QP 使用 R_Key 0x81 进行 RDMA Write/Read 到 MR 1
     - 远程 QP 使用 R_Key 0x82 进行 RDMA Write/Read 到 MR 2
     - RDMA 操作时，远程端必须提供正确的 R_Key

9. 资源创建顺序
   ──────────────
   1. 创建 Context (ibv_open_device)
   2. 创建 PD (ibv_alloc_pd)
   3. 注册 MR (ibv_reg_mr) - 需要 PD
   4. 创建 CQ (ibv_create_cq) - 需要 Context
   5. 创建 AH (ibv_create_ah) - 需要 PD（仅 UD QP 需要）
   6. 创建 QP (ibv_create_qp) - 需要 PD 和 CQ
   7. 提交 WR (ibv_post_send/recv) - 需要 QP 和 MR（UD QP 还需要 AH）

10. 实际应用场景
   ──────────────
   • 多租户隔离：不同应用使用不同 PD，确保安全隔离
   • 资源管理：同一应用的不同模块可以使用不同 PD
   • 权限控制：通过 PD 限制哪些 QP 可以访问哪些 MR
   • 性能优化：合理组织 PD 内的资源，减少跨 PD 访问开销

概念关系图

以下 Mermaid 图表展示了 InfiniBand 关键概念之间的关系：

graph TB
    subgraph Hardware["硬件层"]
        CA[CA
Channel Adapter
通道适配器]
        Port[Port
端口]
    end
    
    subgraph Context["上下文层"]
        Context_Obj[Context
上下文]
        PD[PD
Protection Domain
保护域]
    end
    
    subgraph Memory["内存管理"]
        MR[MR
Memory Region
内存区域]
        LKey[L_Key
本地密钥]
        RKey[R_Key
远程密钥]
        Buffer[Buffer
缓冲区]
    end
    
    subgraph Queue["队列层"]
        QP[QP
Queue Pair
队列对]
        SQ[SQ
Send Queue
发送队列]
        RQ[RQ
Receive Queue
接收队列]
        CQ[CQ
Completion Queue
完成队列]
    end
    
    subgraph Operation["操作层"]
        WR[WR
Work Request
工作请求]
        SGE[SGE
Scatter/Gather Elements
分散/聚集元素]
        SendWR[Send WR]
        RecvWR[Receive WR]
        RDMAWriteWR[RDMA Write WR]
        RDMAReadWR[RDMA Read WR]
    end
    
    subgraph Network["网络层"]
        LID[LID
Local Identifier
本地标识符]
        CM[CM
Connection Manager
连接管理器]
    end
    
    %% Hardware relationships
    CA --> Port
    
    %% Context relationships
    CA --> Context_Obj
    Context_Obj --> PD
    
    %% Memory relationships
    PD --> MR
    MR --> LKey
    MR --> RKey
    MR --> Buffer
    
    %% Queue relationships
    PD --> QP
    QP --> SQ
    QP --> RQ
    QP --> CQ
    CQ --> QP
    
    %% Operation relationships
    SQ --> WR
    RQ --> WR
    WR --> SGE
    SGE --> MR
    SGE --> LKey
    WR --> SendWR
    WR --> RecvWR
    WR --> RDMAWriteWR
    WR --> RDMAReadWR
    RDMAWriteWR --> RKey
    RDMAReadWR --> RKey
    
    %% Network relationships
    Port --> LID
    CM --> QP
    
    %% Completion flow
    WR -->|完成通知| CQ
    
    style CA fill:#e1f5ff
    style PD fill:#fff4e1
    style MR fill:#e8f5e9
    style QP fill:#f3e5f5
    style CQ fill:#fce4ec
    style WR fill:#fff9c4

数据流关系图

以下图表展示了数据在 InfiniBand 系统中的流动路径：

sequenceDiagram
    participant App as 应用程序
    participant QP as Queue Pair
    participant SQ as Send Queue
    participant RQ as Receive Queue
    participant CQ as Completion Queue
    participant MR as Memory Region
    participant CA as Channel Adapter
    participant Network as InfiniBand网络
    
    Note over App,Network: 发送数据流程
    App->>MR: 注册内存区域
    App->>SQ: 提交 Send WR (包含 SGE)
    SQ->>CA: 处理工作请求
    CA->>Network: 发送数据包
    Network->>CA: 确认/完成
    CA->>CQ: 生成完成事件
    CQ->>App: 通知应用完成
    
    Note over App,Network: 接收数据流程
    App->>MR: 注册内存区域
    App->>RQ: 提交 Receive WR (包含 SGE)
    Network->>CA: 接收数据包
    CA->>RQ: 匹配 Receive WR
    CA->>MR: 写入数据到内存
    CA->>CQ: 生成完成事件
    CQ->>App: 通知应用完成
    
    Note over App,Network: RDMA Write 流程
    App->>MR: 注册内存区域(获取R_Key)
    App->>SQ: 提交 RDMA Write WR (包含R_Key)
    SQ->>CA: 处理 RDMA Write
    CA->>Network: 发送 RDMA Write 请求
    Network->>CA: 远程CA接收请求
    CA->>MR: 直接写入远程内存(无需CPU参与)
    CA->>CQ: 生成完成事件
    CQ->>App: 通知应用完成

层次结构图

以下图表展示了 InfiniBand 编程模型的层次结构：

graph TD
    subgraph Level1["应用层"]
        App[应用程序]
    end
    
    subgraph Level2["Verbs API层"]
        Verbs[ibVerbs API]
    end
    
    subgraph Level3["资源管理层"]
        PD_Res[PD: 保护域]
        MR_Res[MR: 内存区域]
        QP_Res[QP: 队列对]
        CQ_Res[CQ: 完成队列]
    end
    
    subgraph Level4["操作层"]
        WR_Op[WR: 工作请求]
        SGE_Op[SGE: 分散/聚集元素]
    end
    
    subgraph Level5["硬件层"]
        CA_HW[CA: 通道适配器]
        Port_HW[Port: 端口]
    end
    
    App --> Verbs
    Verbs --> PD_Res
    Verbs --> MR_Res
    Verbs --> QP_Res
    Verbs --> CQ_Res
    QP_Res --> WR_Op
    WR_Op --> SGE_Op
    SGE_Op --> MR_Res
    WR_Op --> CQ_Res
    QP_Res --> CA_HW
    CA_HW --> Port_HW
    
    style Level1 fill:#e3f2fd
    style Level2 fill:#f1f8e9
    style Level3 fill:#fff3e0
    style Level4 fill:#fce4ec
    style Level5 fill:#e0f2f1

关键概念总结表

编程流程

典型的 InfiniBand 编程流程：

1. 打开设备: ibv_open_device() - 获取 Context
2. 分配保护域: ibv_alloc_pd() - 创建 PD
3. 注册内存: ibv_reg_mr() - 创建 MR，获得 L_Key 和 R_Key
4. 创建完成队列: ibv_create_cq() - 创建 CQ
5. 创建地址句柄: ibv_create_ah() - 创建 AH（仅 UD QP 需要）
6. 创建队列对: ibv_create_qp() - 创建 QP，关联 CQ
7. 建立连接: 使用 CM 或手动配置 QP 状态
8. 提交工作请求: ibv_post_send(), ibv_post_recv() - 提交 WR（UD QP 的 Send WR 需要包含 AH）
9. 轮询完成: ibv_poll_cq() - 检查完成事件
10. 清理资源: 销毁 QP, AH, CQ, MR, PD，关闭设备

参考资料

• RDMA Aware Networks Programming User Manual
• Linux Kernel InfiniBand Documentation
• ibVerbs Manual Pages

概述

动态插桩（Dynamic Instrumentation）是在程序运行时插入监控代码的技术，无需重新编译程序即可进行性能分析和调试。本文介绍 C/C++ 程序中常用的动态插桩工具，重点关注函数调用次数和耗时统计（平均、最小、最大、总计），以及是否支持 attach 到正在运行的进程。

重要说明：耗时统计的范围

不同工具在统计函数耗时时的行为存在重要差异：

• 墙上时钟时间（Wall-clock Time）：包括函数执行期间的所有时间，包括 CPU 执行时间、IO 等待时间、sleep 时间等。这是函数从开始到结束的”真实”耗时。
• CPU 时间（CPU Time）：只包括函数在 CPU 上实际执行的时间，不包括 IO 等待和 sleep 时间。
• 用户态 CPU 时间（User CPU Time）：只包括在用户态执行的时间，不包括内核态时间。

大多数动态插桩工具默认统计的是墙上时钟时间，这意味着如果函数中包含 IO 操作（如文件读写、网络通信）或 sleep，这些时间也会被计入总耗时。这对于理解函数的”真实”执行时间很有帮助，但需要注意区分 CPU 密集型操作和 IO 密集型操作。

动态插桩工具对比

详细工具介绍

1. eBPF/BCC

简介：基于 eBPF（Extended Berkeley Packet Filter）的现代动态跟踪工具集，BCC 提供了高级封装。

特点：

• ✅ 支持 attach 到正在运行的进程
• ✅ 极低开销，内核验证保证安全
• ✅ 可以统计函数调用次数和耗时（min/max/avg/total）
• ✅ 丰富的工具集（funccount, funclatency, trace 等）
• ⏱️ 耗时统计范围：统计墙上时钟时间（包括 IO、sleep 等所有时间）

权限要求：

• root 权限：拥有所有 eBPF/BCC 功能
• 非 root 用户：需要 CAP_BPF 能力（Linux 5.8+）：

  1 2 3 4

  # 授予用户 CAP_BPF 能力 sudo setcap cap_bpf+ep /usr/bin/python3 # 或授予特定 BCC 工具 sudo setcap cap_bpf+ep /usr/share/bcc/tools/funccount

• attach 到其他用户的进程：需要 root 权限或 CAP_SYS_PTRACE 能力
• 加载 eBPF 程序：需要 root 权限或 CAP_BPF 能力（Linux 5.8+）
• 读取内核符号：需要 root 权限或 CAP_SYS_ADMIN 能力

限制：

• 需要 Linux 4.1+ 内核（eBPF 支持）

使用示例：

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

# funclatency - 统计函数耗时分布
funclatency -p <pid> 'target_function'

# funccount - 统计函数调用次数
funccount -p <pid> 'target_function'

# 自定义 BCC 脚本统计详细指标
from bcc import BPF

bpf_text = """
#include <uapi/linux/ptrace.h>

BPF_HASH(start, u32);
BPF_HASH(count, u32);
BPF_HASH(total_time, u64);
BPF_HASH(min_time, u64);
BPF_HASH(max_time, u64);

int trace_entry(struct pt_regs *ctx) {
    u32 pid = bpf_get_current_pid_tgid();
    u64 ts = bpf_ktime_get_ns();
    start.update(&pid, &ts);
    u64 zero = 0;
    count.update(&pid, &zero);
    u64 *val = count.lookup(&pid);
    if (val) {
        (*val)++;
        count.update(&pid, val);
    }
    return 0;
}

int trace_return(struct pt_regs *ctx) {
    u32 pid = bpf_get_current_pid_tgid();
    u64 *tsp = start.lookup(&pid);
    if (tsp == 0) {
        return 0;
    }
    u64 delta = bpf_ktime_get_ns() - *tsp;
    
    // 更新统计信息
    u64 *total = total_time.lookup(&pid);
    u64 *min = min_time.lookup(&pid);
    u64 *max = max_time.lookup(&pid);
    
    if (total) {
        *total += delta;
    } else {
        total_time.update(&pid, &delta);
    }
    
    if (!min || delta < *min) {
        min_time.update(&pid, &delta);
    }
    
    if (!max || delta > *max) {
        max_time.update(&pid, &delta);
    }
    
    start.delete(&pid);
    return 0;
}
"""

# attach 到进程
b = BPF(text=bpf_text)
b.attach_uprobe(name="target_program", sym="target_function", fn_name="trace_entry")
b.attach_uretprobe(name="target_program", sym="target_function", fn_name="trace_return")

2. bptrace

简介：基于 eBPF 的轻量级动态追踪工具，专门用于监控和分析正在运行的 C/C++ 程序。bptrace 提供了简洁的命令行接口，可以方便地统计函数调用次数和执行时间。

特点：

• ✅ 支持 attach 到正在运行的进程
• ✅ 可以统计函数调用次数和耗时（min/max/avg/total）
• ✅ 极低开销，基于 eBPF 技术
• ✅ 简洁的命令行接口，易于使用
• ✅ 无需修改程序源码或重新编译
• ⏱️ 耗时统计范围：统计墙上时钟时间（包括 IO、sleep 等所有时间）

权限要求：

• root 权限：拥有所有 bptrace 功能
• 非 root 用户：需要 CAP_BPF 能力（Linux 5.8+）：

  1 2	# 授予用户 CAP_BPF 能力 sudo setcap cap_bpf+ep /usr/bin/bptrace

• attach 到其他用户的进程：需要 root 权限或 CAP_SYS_PTRACE 能力
• 加载 eBPF 程序：需要 root 权限或 CAP_BPF 能力（Linux 5.8+）

限制：

• 需要 Linux 内核支持 eBPF（通常 4.1+）
• Linux 5.8+ 才支持非 root 用户使用 CAP_BPF
• 主要适用于用户态函数追踪
• 需要目标程序包含调试符号信息（或使用地址）

使用示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 统计函数调用次数
bptrace -p <pid> -f 'target_function' -c

# 统计函数耗时（包括平均、最小、最大、总耗时）
bptrace -p <pid> -f 'target_function' -t

# 同时统计调用次数和耗时
bptrace -p <pid> -f 'target_function' -c -t

# 统计多个函数
bptrace -p <pid> -f 'function1,function2' -c -t

# 指定输出格式
bptrace -p <pid> -f 'target_function' -t --format json

# 持续监控并定期输出统计信息
bptrace -p <pid> -f 'target_function' -t --interval 5

输出示例：

1
2
3
4
5
6

Function: target_function
  Call Count: 1000
  Total Time: 50000 us
  Average Time: 50 us
  Min Time: 10 us
  Max Time: 200 us

与 eBPF/BCC 的关系：

• bptrace 可以看作是 BCC 工具集的简化版本，专门针对函数级性能分析
• 相比 BCC，bptrace 提供了更简洁的命令行接口，适合快速分析
• 如果需要更复杂的自定义逻辑，仍需要使用 BCC 编写 Python/C 脚本

3. SystemTap

简介：Linux 系统级动态跟踪工具，功能强大，支持用户态和内核态插桩。

特点：

• ✅ 支持 attach 到正在运行的进程
• ✅ 可以精确统计函数调用次数和耗时（包括 min/max/avg/total）
• ✅ 灵活的脚本语言，可以自定义统计逻辑
• ✅ 低开销（取决于脚本复杂度）
• ⏱️ 耗时统计范围：统计墙上时钟时间（包括 IO、sleep 等所有时间）

权限要求：

• root 权限：拥有所有 SystemTap 功能
• 非 root 用户：需要加入特定组：
  • stapdev 组：可以加载任意 SystemTap 模块（需要 root 权限添加）
  • stapusr 组：只能使用预编译的 SystemTap 模块（更安全）
• attach 到其他用户的进程：需要 root 权限或 CAP_SYS_PTRACE 能力
• 内核模块加载：需要 root 权限或 CAP_SYS_MODULE 能力

限制：

• 需要安装 kernel-devel 包（用于编译 SystemTap 模块）

使用示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 统计函数调用次数和耗时
probe process("/path/to/program").function("target_function") {
    start_time = gettimeofday_us()
}

probe process("/path/to/program").function("target_function").return {
    call_count++
    elapsed = gettimeofday_us() - start_time
    total_time += elapsed
    if (elapsed < min_time || min_time == 0) min_time = elapsed
    if (elapsed > max_time) max_time = elapsed
}

probe end {
    printf("调用次数: %d\n", call_count)
    printf("总耗时: %d us\n", total_time)
    printf("平均耗时: %d us\n", total_time / call_count)
    printf("最小耗时: %d us\n", min_time)
    printf("最大耗时: %d us\n", max_time)
}

# attach 到运行中的进程
stap -x <pid> script.stp

4. perf + uprobes

简介：Linux 内核自带的性能分析工具，通过 uprobes 机制实现用户态动态插桩。

特点：

• ✅ 支持 attach 到正在运行的进程
• ✅ 低开销，基于采样和事件计数
• ✅ 可以统计函数调用次数和耗时
• ✅ 无需修改程序源码或重新编译
• ⏱️ 耗时统计范围：默认统计墙上时钟时间（包括 IO、sleep 等），也可配置为统计 CPU 时间

权限要求：

• root 权限：最直接的方式，拥有所有 perf 功能
• 非 root 用户：需要设置 /proc/sys/kernel/perf_event_paranoid：
  • -1：允许所有用户使用 perf（不推荐，安全风险）
  • 0：允许用户分析自己的进程
  • 1：允许用户分析自己的进程和内核（默认值）
  • 2：只允许 root 使用 perf
• attach 到其他用户的进程：需要 root 权限或 CAP_SYS_PTRACE 能力
• 查看内核符号：需要 root 权限或设置 perf_event_paranoid <= 1

限制：

• 统计详细耗时需要额外脚本处理

使用示例：

1
2
3
4
5
6
7

# 统计函数调用次数
perf probe -x ./program function_name
perf record -e probe_program:function_name ./program

# 统计函数耗时（需要自定义脚本或结合其他工具）
perf record -g -p <pid>  # attach 到运行中的进程
perf report

5. DTrace

简介：Sun Microsystems 开发的动态跟踪框架，现支持 Solaris、FreeBSD、macOS。

特点：

• ✅ 支持 attach 到正在运行的进程
• ✅ 可以统计函数调用次数和耗时（min/max/avg/total）
• ✅ 低开销，功能强大
• ✅ 支持聚合统计（aggregations）
• ⏱️ 耗时统计范围：统计墙上时钟时间（包括 IO、sleep 等所有时间）

权限要求：

• macOS：
  • 需要关闭 SIP（System Integrity Protection）或使用特殊权限
  • 或者使用 sudo 运行（需要管理员权限）
• Solaris/FreeBSD：
  • 需要 root 权限或 dtrace_kernel 权限
• Linux：
  • 支持有限（需要 Oracle Linux 或通过 SystemTap）
  • 通常需要 root 权限

限制：

• Linux 上支持有限（需要 Oracle Linux 或通过 SystemTap）

使用示例：

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

#!/usr/sbin/dtrace -s

pid$target:target:function_name:entry
{
    self->start = timestamp;
    @count[probefunc] = count();
}

pid$target:target:function_name:return
/self->start/
{
    this->elapsed = timestamp - self->start;
    @time["total"] = sum(this->elapsed);
    @time["avg"] = avg(this->elapsed);
    @time["min"] = min(this->elapsed);
    @time["max"] = max(this->elapsed);
    self->start = 0;
}

END
{
    printa("调用次数: %@d\n", @count);
    printa("总耗时: %@d ns\n", @time["total"]);
    printa("平均耗时: %@d ns\n", @time["avg"]);
    printa("最小耗时: %@d ns\n", @time["min"]);
    printa("最大耗时: %@d ns\n", @time["max"]);
}

# 使用方式
dtrace -s script.d -p <pid>

简介：基于 eBPF 的轻量级动态追踪工具，专门用于监控和分析正在运行的 C/C++ 程序。bptrace 提供了简洁的命令行接口，可以方便地统计函数调用次数和执行时间。

特点：

• ✅ 支持 attach 到正在运行的进程
• ✅ 可以统计函数调用次数和耗时（min/max/avg/total）
• ✅ 极低开销，基于 eBPF 技术
• ✅ 简洁的命令行接口，易于使用
• ✅ 无需修改程序源码或重新编译
• ⏱️ 耗时统计范围：统计墙上时钟时间（包括 IO、sleep 等所有时间）

权限要求：

• root 权限：拥有所有 bptrace 功能
• 非 root 用户：需要 CAP_BPF 能力（Linux 5.8+）：

  1 2	# 授予用户 CAP_BPF 能力 sudo setcap cap_bpf+ep /usr/bin/bptrace

• attach 到其他用户的进程：需要 root 权限或 CAP_SYS_PTRACE 能力
• 加载 eBPF 程序：需要 root 权限或 CAP_BPF 能力（Linux 5.8+）

限制：

• 需要 Linux 内核支持 eBPF（通常 4.1+）
• Linux 5.8+ 才支持非 root 用户使用 CAP_BPF
• 主要适用于用户态函数追踪
• 需要目标程序包含调试符号信息（或使用地址）

使用示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 统计函数调用次数
bptrace -p <pid> -f 'target_function' -c

# 统计函数耗时（包括平均、最小、最大、总耗时）
bptrace -p <pid> -f 'target_function' -t

# 同时统计调用次数和耗时
bptrace -p <pid> -f 'target_function' -c -t

# 统计多个函数
bptrace -p <pid> -f 'function1,function2' -c -t

# 指定输出格式
bptrace -p <pid> -f 'target_function' -t --format json

# 持续监控并定期输出统计信息
bptrace -p <pid> -f 'target_function' -t --interval 5

输出示例：

1
2
3
4
5
6

Function: target_function
  Call Count: 1000
  Total Time: 50000 us
  Average Time: 50 us
  Min Time: 10 us
  Max Time: 200 us

与 eBPF/BCC 的关系：

• bptrace 可以看作是 BCC 工具集的简化版本，专门针对函数级性能分析
• 相比 BCC，bptrace 提供了更简洁的命令行接口，适合快速分析
• 如果需要更复杂的自定义逻辑，仍需要使用 BCC 编写 Python/C 脚本

6. Intel Pin

简介：Intel 开发的动态二进制插桩框架，功能强大但开销较高。

特点：

• ❌ 不支持 attach，必须在程序启动时插桩
• ✅ 可以统计函数调用次数和耗时（min/max/avg/total）
• ✅ 支持细粒度插桩（指令级）
• ⚠️ 高开销（通常 10-100 倍）
• ⏱️ 耗时统计范围：统计墙上时钟时间（包括 IO、sleep 等所有时间）

权限要求：

• 普通用户权限：Intel Pin 不需要特殊权限，普通用户即可使用
• 读取目标程序：需要目标程序的读取权限
• 写入输出文件：需要输出目录的写入权限

限制：

• 不支持 attach 到运行中的进程
• 高开销，不适合生产环境
• 主要适用于详细分析和研究

使用示例：

1
2
3
4
5

# 使用 Pin 工具统计函数调用
pin -t source/tools/ManualExamples/obj-intel64/inscount0.so -- ./program

# 自定义 Pin 工具统计函数耗时
# 需要编写 Pin 工具（C++）

7. DynamoRIO

简介：跨平台的动态二进制插桩框架，支持 Windows、Linux、macOS。

特点：

• ❌ 不支持 attach，必须在程序启动时插桩
• ✅ 可以统计函数调用次数和耗时（min/max/avg/total）
• ✅ 跨平台支持
• ⚠️ 高开销
• ⏱️ 耗时统计范围：统计墙上时钟时间（包括 IO、sleep 等所有时间）

权限要求：

• 普通用户权限：DynamoRIO 不需要特殊权限，普通用户即可使用
• 读取目标程序：需要目标程序的读取权限
• 写入输出文件：需要输出目录的写入权限
• Windows：可能需要管理员权限（取决于目标程序）

限制：

• 不支持 attach 到运行中的进程
• 高开销
• 需要编写客户端工具

使用示例：

1
2
3
4
5
6

# 使用 DynamoRIO 工具
drrun -tool calltrace -- ./program
drrun -tool memtrace -- ./program

# 自定义工具统计函数耗时
# 需要编写 DynamoRIO 客户端（C++）

8. Valgrind Callgrind

简介：Valgrind 工具集中的调用图分析工具。

特点：

• ❌ 不支持 attach，必须在程序启动时插桩
• ✅ 可以统计函数调用次数和耗时
• ✅ 生成详细的调用图
• ⚠️ 极高开销（通常 20-100 倍）
• ⏱️ 耗时统计范围：统计 CPU 时间（不包括 IO 等待和 sleep 时间），只统计函数在 CPU 上实际执行的时间

权限要求：

• 普通用户权限：Valgrind 不需要特殊权限，普通用户即可使用
• 读取目标程序：需要目标程序的读取权限
• 写入输出文件：需要输出目录的写入权限
• 内存访问：Valgrind 需要访问进程内存，但不需要 root 权限

限制：

• 不支持 attach
• 极高开销，不适合生产环境
• 主要用于开发阶段的详细分析

使用示例：

1
2
3
4
5
6

# 使用 Callgrind 分析
valgrind --tool=callgrind ./program

# 查看结果
callgrind_annotate callgrind.out.<pid>
kcachegrind callgrind.out.<pid>  # GUI 工具

9. LD_PRELOAD + 自定义库

简介：通过 LD_PRELOAD 机制拦截库函数调用，实现简单的动态插桩。

特点：

• ❌ 不支持 attach，需要在启动时设置环境变量
• ✅ 可以统计库函数调用次数和耗时
• ✅ 低开销
• ⚠️ 只能拦截库函数，不能拦截静态函数
• ⏱️ 耗时统计范围：统计墙上时钟时间（包括 IO、sleep 等所有时间），取决于使用的计时函数（如 gettimeofday()）

权限要求：

• 普通用户权限：LD_PRELOAD 不需要特殊权限，普通用户即可使用
• 读取目标程序：需要目标程序的读取权限
• 加载共享库：需要共享库的读取权限
• 设置环境变量：需要设置 LD_PRELOAD 环境变量的权限（通常都有）

限制：

• 不支持 attach
• 只能拦截库函数，不能拦截静态函数或内联函数
• 需要手动编写包装代码

使用示例：

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

// wrapper.c - 包装库函数
#define _GNU_SOURCE
#include <dlfcn.h>
#include <stdio.h>
#include <time.h>
#include <sys/time.h>

static unsigned long call_count = 0;
static unsigned long total_time = 0;
static unsigned long min_time = ULONG_MAX;
static unsigned long max_time = 0;

void __attribute__((constructor)) init() {
    // 初始化
}

void __attribute__((destructor)) fini() {
    printf("调用次数: %lu\n", call_count);
    printf("总耗时: %lu us\n", total_time);
    if (call_count > 0) {
        printf("平均耗时: %lu us\n", total_time / call_count);
        printf("最小耗时: %lu us\n", min_time);
        printf("最大耗时: %lu us\n", max_time);
    }
}

// 包装目标函数
int target_function(int arg) {
    struct timeval start, end;
    gettimeofday(&start, NULL);
    
    // 调用原始函数
    int (*original_func)(int) = dlsym(RTLD_NEXT, "target_function");
    int result = original_func(arg);
    
    gettimeofday(&end, NULL);
    unsigned long elapsed = (end.tv_sec - start.tv_sec) * 1000000 + 
                           (end.tv_usec - start.tv_usec);
    
    call_count++;
    total_time += elapsed;
    if (elapsed < min_time) min_time = elapsed;
    if (elapsed > max_time) max_time = elapsed;
    
    return result;
}

1
2
3
4
5

# 编译包装库
gcc -shared -fPIC -o wrapper.so wrapper.c -ldl

# 使用
LD_PRELOAD=./wrapper.so ./program

10. ltrace

简介：Linux 库函数调用跟踪工具。

特点：

• ✅ 支持 attach 到正在运行的进程
• ✅ 可以统计库函数调用次数
• ⚠️ 只能统计库函数，不能统计自定义函数
• ⚠️ 耗时统计功能有限
• ⏱️ 耗时统计范围：统计墙上时钟时间（包括 IO、sleep 等所有时间），但功能有限

权限要求：

• 跟踪自己的进程：普通用户权限即可
• attach 到其他用户的进程：需要 root 权限或 CAP_SYS_PTRACE 能力
• 读取目标程序：需要目标程序的读取权限
• ptrace 系统调用：attach 功能依赖 ptrace，受 /proc/sys/kernel/yama/ptrace_scope 限制：
  • 0：允许同一用户调试其权限范围内的任意进程
  • 1：只允许调试直接子进程（默认值）
  • 2：只有 root 或具备 CAP_SYS_PTRACE 的进程可以使用 ptrace
  • 3：完全禁用 ptrace

限制：

• 只能跟踪库函数
• 耗时统计功能有限
• 不适合统计自定义函数

使用示例：

1
2
3
4
5

# 跟踪库函数调用
ltrace -p <pid> -c  # 统计调用次数

# 跟踪特定函数
ltrace -p <pid> -e 'malloc+free'

耗时统计范围详解

墙上时钟时间 vs CPU 时间

理解不同工具统计的耗时范围对于正确解读性能数据至关重要：

1. 墙上时钟时间（Wall-clock Time）

包括的内容：

• ✅ CPU 执行时间
• ✅ IO 等待时间（文件读写、网络通信等）
• ✅ sleep 时间（sleep(), usleep(), nanosleep() 等）
• ✅ 线程阻塞时间（等待锁、条件变量等）
• ✅ 上下文切换时间

适用场景：

• 了解函数的”真实”执行时间
• 分析 IO 密集型函数的性能
• 诊断包含阻塞操作的函数
• 评估用户体验相关的性能指标

示例：

1
2
3
4
5
6
7
8
9
10
11
12

void slow_function() {
    // CPU 执行：1ms
    do_computation();
    
    // IO 等待：100ms
    read_from_disk();
    
    // sleep：50ms
    sleep(0.05);
    
    // 总墙上时钟时间：~151ms
}

使用墙上时钟时间的工具：

• SystemTap、DTrace、eBPF/BCC、bptrace
• Intel Pin、DynamoRIO
• LD_PRELOAD（使用 gettimeofday() 等）
• perf（默认配置）

2. CPU 时间（CPU Time）

包括的内容：

• ✅ CPU 执行时间
• ❌ 不包括 IO 等待时间
• ❌ 不包括 sleep 时间
• ❌ 不包括 线程阻塞时间

适用场景：

• 分析 CPU 密集型函数的性能
• 评估算法的计算复杂度
• 识别 CPU 热点
• 优化计算逻辑

示例：

1
2
3
4
5
6
7
8
9
10
11
12

void slow_function() {
    // CPU 执行：1ms（计入）
    do_computation();
    
    // IO 等待：100ms（不计入）
    read_from_disk();
    
    // sleep：50ms（不计入）
    sleep(0.05);
    
    // CPU 时间：~1ms（只包括 CPU 执行时间）
}

使用 CPU 时间的工具：

• Valgrind Callgrind（主要统计 CPU 时间）

3. 实际应用建议

选择统计范围的原则：

1. IO 密集型函数：使用墙上时钟时间

   • 文件操作、网络通信、数据库查询
   • 需要了解包括等待时间在内的总耗时

2. CPU 密集型函数：两种时间都关注

   • 算法计算、数据处理
   • CPU 时间用于评估算法效率
   • 墙上时钟时间用于评估用户体验

3. 混合型函数：优先使用墙上时钟时间

   • 大多数实际应用中的函数
   • 墙上时钟时间更能反映真实性能

注意事项：

• ⚠️ 多线程环境：墙上时钟时间可能小于 CPU 时间（并行执行）
• ⚠️ IO 操作：如果函数包含 IO，墙上时钟时间会显著大于 CPU 时间
• ⚠️ sleep 操作：如果函数包含 sleep，墙上时钟时间会包含 sleep 时间
• ⚠️ 上下文切换：频繁的上下文切换会增加墙上时钟时间

如何区分 CPU 时间和 IO 时间：

如果使用统计墙上时钟时间的工具，可以通过以下方式区分：

1. 结合系统调用跟踪：使用 strace 或 perf trace 查看 IO 系统调用
2. 分析函数内部：如果函数耗时很长但 CPU 使用率低，可能是 IO 等待
3. 使用 perf 的 CPU 时间模式：perf record -e cpu-clock 可以统计 CPU 时间

权限要求总结

权限类型说明

1. root 权限

• 含义：拥有系统最高权限
• 获取方式：使用 sudo 或切换到 root 用户
• 适用工具：perf、SystemTap、DTrace、eBPF/BCC、bptrace（默认需要）

2. Linux Capabilities（能力）

现代 Linux 系统使用 capabilities 机制，允许非 root 用户执行特定操作：

• CAP_BPF：加载 eBPF 程序（Linux 5.8+）

  1	sudo setcap cap_bpf+ep /path/to/tool

• CAP_SYS_PTRACE：使用 ptrace attach 到其他进程

  1	sudo setcap cap_sys_ptrace+ep /path/to/tool

• CAP_SYS_ADMIN：访问内核符号和系统管理功能
• CAP_SYS_MODULE：加载内核模块

3. 普通用户权限

• 含义：不需要特殊权限，普通用户即可使用
• 适用工具：Intel Pin、DynamoRIO、Valgrind Callgrind、LD_PRELOAD

4. 组权限

• stapdev 组：SystemTap 开发组，可以加载任意模块
• stapusr 组：SystemTap 用户组，只能使用预编译模块

权限配置示例

配置 perf 非 root 使用

1
2
3
4
5
6

# 允许用户分析自己的进程
echo 0 | sudo tee /proc/sys/kernel/perf_event_paranoid

# 或永久配置
echo "kernel.perf_event_paranoid = 0" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

配置 eBPF/BCC 非 root 使用（Linux 5.8+）

1
2
3
4
5
6

# 授予 Python 解释器 CAP_BPF 能力
sudo setcap cap_bpf+ep /usr/bin/python3

# 或授予特定 BCC 工具
sudo setcap cap_bpf+ep /usr/share/bcc/tools/funccount
sudo setcap cap_bpf+ep /usr/share/bcc/tools/funclatency

配置 SystemTap 非 root 使用

1
2
3
4

# 将用户添加到 stapusr 组
sudo usermod -a -G stapusr $USER

# 需要重新登录使组权限生效

配置 ptrace（用于 attach 功能）

1
2
3
4
5
6
7
8

# 查看当前 ptrace_scope 设置
cat /proc/sys/kernel/yama/ptrace_scope

# 允许同一用户调试其权限范围内的进程（开发环境）
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

# 或永久配置
echo "kernel.yama.ptrace_scope = 0" | sudo tee -a /etc/sysctl.conf

权限要求快速参考

安全注意事项

⚠️ 生产环境建议：

• 避免使用 perf_event_paranoid = -1（允许所有用户）
• 避免将用户添加到 stapdev 组（安全风险）
• 谨慎配置 ptrace_scope = 0（允许任意进程调试）
• 使用 capabilities 而非 root 权限（最小权限原则）
• 定期审查已授予的 capabilities

工具选择建议

需要 attach 到运行中进程

1. eBPF/BCC（推荐）：现代、低开销、功能强大
2. bptrace（推荐）：简洁易用，专门针对函数级性能分析
3. SystemTap：功能强大，脚本灵活
4. perf + uprobes：系统自带，简单易用
5. DTrace：如果使用 Solaris/FreeBSD/macOS

不需要 attach（可以重新启动程序）

1. Intel Pin / DynamoRIO：需要详细分析时使用
2. Valgrind Callgrind：需要调用图分析时使用
3. LD_PRELOAD：简单场景，只统计库函数

统计指标对比

总结

对于 C/C++ 程序的动态插桩，推荐使用以下工具：

1. 生产环境 + 需要 attach：bptrace、eBPF/BCC 或 SystemTap
2. 开发调试 + 详细分析：Intel Pin 或 DynamoRIO
3. 简单场景 + 库函数统计：LD_PRELOAD
4. 系统级分析：perf + uprobes

选择工具时需要考虑：

• 是否需要 attach 到运行中的进程
• 对性能开销的容忍度
• 需要统计的详细程度
• 系统平台和权限限制
• 耗时统计范围：大多数工具统计墙上时钟时间（包括 IO、sleep），只有 Valgrind Callgrind 统计 CPU 时间（不包括 IO、sleep）
• 权限要求：
  • 内核级插桩工具（perf、SystemTap、eBPF/BCC、bptrace）通常需要 root 权限或特殊 capabilities
  • 二进制插桩工具（Intel Pin、DynamoRIO、Valgrind）通常只需要普通用户权限
  • attach 到其他用户的进程需要 root 权限或 CAP_SYS_PTRACE 能力

代码

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

template <typename Predicate>
void SpinWaitWhile(Predicate pred) {
    int count = 0;
    while (pred()) {
        if (count < 100) {
            tbb::detail::machine_pause(10);
            ++count;
        } else if (count < 200) {
            utils::yield();
            ++count;
        } else {
            std::this_thread::sleep_for(std::chrono::microseconds(count/100));
            if (count < 10000) {
                count += 100;
            }
        }
    }
}

static inline void machine_pause(int32_t delay) {
#if __TBB_x86_64 || __TBB_x86_32
    while (delay-- > 0) { _mm_pause(); }
#elif __ARM_ARCH_7A__ || __aarch64__
    while (delay-- > 0) { __asm__ __volatile__("isb sy" ::: "memory"); }
#else /* Generic */
    (void)delay; // suppress without including _template_helpers.h
    yield();
#endif
}

函数说明与CPU周期分析

该自旋锁退避算法采用三级退避策略，逐步降低CPU占用：

1. 第一阶段：machine_pause() (count < 100)

x86架构 (_mm_pause())

• 功能：执行 PAUSE 指令，提示CPU当前处于自旋等待状态
• 系统调用：❌ 否 - 纯用户态CPU指令
• 进入内核态：❌ 否 - 完全在用户态执行
• 调用调度器：❌ 否 - 不涉及操作系统调度
• CPU周期：
  • Intel处理器：约 140个周期（Skylake及以后架构）
  • AMD处理器：约 10-40个周期
  • 代码中调用 machine_pause(10)，实际执行10次 PAUSE 指令
• 开销来源：
  • CPU指令执行延迟（主要开销）
  • 流水线停顿（Pipeline Stall）
  • 无系统调用开销、无上下文切换开销
• 作用：
  • 降低CPU功耗（避免超线程的忙等待）
  • 减少内存顺序违规（Memory Order Violation）
  • 在超线程环境下，让出执行资源给同核心的另一个线程
• 总开销：每次循环约 1400-4000个周期（Intel）或 100-400个周期（AMD）

ARM架构 (isb sy)

• 功能：指令同步屏障（Instruction Synchronization Barrier），确保所有指令完成
• 系统调用：❌ 否 - 纯用户态CPU指令
• 进入内核态：❌ 否 - 完全在用户态执行
• 调用调度器：❌ 否 - 不涉及操作系统调度
• CPU周期：约 10-50个周期（取决于具体ARM核心）
• 开销来源：
  • CPU指令执行延迟（主要开销）
  • 指令流水线同步等待
  • 无系统调用开销、无上下文切换开销
• 作用：确保内存访问顺序，避免乱序执行导致的问题
• 总开销：每次循环约 100-500个周期

2. 第二阶段：utils::yield() (100 ≤ count < 200)

• 功能：主动让出CPU时间片，通常对应 sched_yield() 系统调用
• 系统调用：✅ 是 - 调用 sched_yield() 系统调用（Linux）或 SwitchToThread()（Windows）
• 进入内核态：✅ 是 - 必须进入内核态执行系统调用
• 调用调度器：✅ 是 - 主动调用内核调度器，将当前线程移出运行队列
• CPU周期：
  • 系统调用开销：约 1000-3000个周期
    • 用户态到内核态切换：~200-500周期
    • 系统调用处理：~300-1000周期
    • 内核态到用户态切换：~200-500周期
  • 调度器开销：约 2000-5000个周期
    • 调度器决策：~500-1500周期
    • 运行队列操作：~300-800周期
  • 上下文切换开销：约 3000-15000个周期（如果发生线程切换）
    • 寄存器保存/恢复：~1000-3000周期
    • TLB刷新：~500-2000周期
    • 缓存失效：~1500-10000周期
  • 总计：6000-23000个周期
• 开销来源：
  • 系统调用开销：用户态/内核态切换（主要开销之一）
  • 调度器开销：调度决策和运行队列操作
  • 上下文切换开销：如果调度器选择运行其他线程（主要开销）
  • 缓存失效：线程切换导致L1/L2缓存失效
• 作用：
  • 让调度器有机会运行其他线程
  • 避免长时间占用CPU核心
  • 在锁竞争激烈时，给持有锁的线程更多执行机会

3. 第三阶段：sleep_for() (count ≥ 200)

• 功能：线程主动睡眠指定时间
• 系统调用：✅ 是 - 调用 nanosleep() 或 futex() 系统调用（Linux）
• 进入内核态：✅ 是 - 必须进入内核态执行系统调用
• 调用调度器：✅ 是 - 将当前线程移出运行队列，放入等待队列
• CPU周期：
  • 系统调用开销：约 1000-3000个周期
    • 用户态到内核态切换：~200-500周期
    • 系统调用处理（设置定时器）：~500-1500周期
    • 内核态到用户态切换：~200-500周期
  • 调度器开销：约 3000-8000个周期
    • 调度器决策：~500-1500周期
    • 运行队列操作：~500-1000周期
    • 等待队列操作：~500-1000周期
    • 定时器设置：~1500-4500周期
  • 上下文切换开销：约 7000-42000个周期（必然发生）
    • 寄存器保存/恢复：~1000-3000周期
    • TLB刷新：~500-2000周期
    • 缓存失效：~5500-37000周期（L1/L2/L3缓存）
  • 睡眠时间：count/100 微秒（例如 count=200 时睡眠2微秒）
  • 总计：11000-53000个周期 + 睡眠时间
• 开销来源：
  • 系统调用开销：用户态/内核态切换（主要开销之一）
  • 调度器开销：调度决策、队列操作、定时器管理（主要开销之一）
  • 上下文切换开销：线程必然被切换，寄存器、TLB、缓存全部失效（主要开销）
  • 定时器开销：内核定时器设置和管理
  • 唤醒开销：定时器到期后唤醒线程的开销（未计入上述周期）
• 作用：
  • 大幅降低CPU占用
  • 睡眠时间随 count 增长而增加（最大100微秒）
  • 适用于锁竞争非常激烈或持锁时间较长的情况