1 .. include:: ../disclaimer-zh_CN.rst 1 .. include:: ../disclaimer-zh_CN.rst
2 2
3 :Original: Documentation/infiniband/user_mad.r 3 :Original: Documentation/infiniband/user_mad.rst
4 4
5 :翻译: 5 :翻译:
6 6
7 司延腾 Yanteng Si <siyanteng@loongson.cn> 7 司延腾 Yanteng Si <siyanteng@loongson.cn>
8 8
9 :校译: 9 :校译:
10 10
11 王普宇 Puyu Wang <realpuyuwang@gmail.com> 11 王普宇 Puyu Wang <realpuyuwang@gmail.com>
12 时奎亮 Alex Shi <alexs@kernel.org> 12 时奎亮 Alex Shi <alexs@kernel.org>
13 13
14 .. _cn_infiniband_user_mad: 14 .. _cn_infiniband_user_mad:
15 15
16 =============== 16 ===============
17 用户空间MAD访问 17 用户空间MAD访问
18 =============== 18 ===============
19 19
20 设备文件 20 设备文件
21 ======== 21 ========
22 22
23 每个InfiniBand设备的每个端口都有 23 每个InfiniBand设备的每个端口都有一个“umad”设备和一个“issm”设备连接。
24 例如，一个双端口的HCA将有两个um 24 例如，一个双端口的HCA将有两个umad设备和两个issm设备，而一个交换机将
25 有每个类型的一个设备（对于交 25 有每个类型的一个设备（对于交换机端口0）。
26 26
27 创建MAD代理 27 创建MAD代理
28 =========== 28 ===========
29 29
30 一个MAD代理可以通过填写一个结 30 一个MAD代理可以通过填写一个结构体ib_user_mad_reg_req来创建，然后在
31 适当的设备文件的文件描述符上 31 适当的设备文件的文件描述符上调用IB_USER_MAD_REGISTER_AGENT ioctl。
32 如果注册请求成功，结构体中会 32 如果注册请求成功，结构体中会返回一个32位的ID。比如说::
33 33
34 struct ib_user_mad_reg_req req = { /* 34 struct ib_user_mad_reg_req req = { /* ... */ };
35 ret = ioctl(fd, IB_USER_MAD_REGISTER_A 35 ret = ioctl(fd, IB_USER_MAD_REGISTER_AGENT, (char *) &req);
36 if (!ret) 36 if (!ret)
37 my_agent = req.id; 37 my_agent = req.id;
38 else 38 else
39 perror("agent register"); 39 perror("agent register");
40 40
41 代理可以通过IB_USER_MAD_UNREGISTER_AGE 41 代理可以通过IB_USER_MAD_UNREGISTER_AGENT ioctl取消注册。另外，所有
42 通过文件描述符注册的代理在描 42 通过文件描述符注册的代理在描述符关闭时将被取消注册。
43 43
44 2014 44 2014
45 现在提供了一个新的注册IOctl 45 现在提供了一个新的注册IOctl，允许在注册时提供额外的字段。这个注册
46 调用的用户隐含了对pkey_index 46 调用的用户隐含了对pkey_index的使用（见下文）。现在提供了一个新的
47 注册IOctl，允许在注册时提供 47 注册IOctl，允许在注册时提供额外的字段。这个注册调用的用户隐含了对
48 pkey_index的使用（见下文）。 48 pkey_index的使用（见下文）。
49 49
50 接收MADs 50 接收MADs
51 ======== 51 ========
52 52
53 使用read()接收MAD。现在接收端支 53 使用read()接收MAD。现在接收端支持RMPP。传给read()的缓冲区必须至少是
54 一个struct ib_user_mad + 256字节。比 54 一个struct ib_user_mad + 256字节。比如说:
55 55
56 如果传递的缓冲区不足以容纳收 56 如果传递的缓冲区不足以容纳收到的MAD（RMPP），errno被设置为ENOSPC，需
57 要的缓冲区长度被设置在mad.length 57 要的缓冲区长度被设置在mad.length中。
58 58
59 正常MAD(非RMPP)的读取示例:: 59 正常MAD(非RMPP)的读取示例::
60 60
61 struct ib_user_mad *mad; 61 struct ib_user_mad *mad;
62 mad = malloc(sizeof *mad + 256); 62 mad = malloc(sizeof *mad + 256);
63 ret = read(fd, mad, sizeof *mad + 256) 63 ret = read(fd, mad, sizeof *mad + 256);
64 if (ret != sizeof mad + 256) { 64 if (ret != sizeof mad + 256) {
65 perror("read"); 65 perror("read");
66 free(mad); 66 free(mad);
67 } 67 }
68 68
69 RMPP读取示例:: 69 RMPP读取示例::
70 70
71 struct ib_user_mad *mad; 71 struct ib_user_mad *mad;
72 mad = malloc(sizeof *mad + 256); 72 mad = malloc(sizeof *mad + 256);
73 ret = read(fd, mad, sizeof *mad + 256) 73 ret = read(fd, mad, sizeof *mad + 256);
74 if (ret == -ENOSPC)) { 74 if (ret == -ENOSPC)) {
75 length = mad.length; 75 length = mad.length;
76 free(mad); 76 free(mad);
77 mad = malloc(sizeof *mad + len 77 mad = malloc(sizeof *mad + length);
78 ret = read(fd, mad, sizeof *ma 78 ret = read(fd, mad, sizeof *mad + length);
79 } 79 }
80 if (ret < 0) { 80 if (ret < 0) {
81 perror("read"); 81 perror("read");
82 free(mad); 82 free(mad);
83 } 83 }
84 84
85 除了实际的MAD内容外，其他结构 85 除了实际的MAD内容外，其他结构体ib_user_mad字段将被填入收到的MAD的信
86 息。例如，远程LID将在mad.lid中。 86 息。例如，远程LID将在mad.lid中。
87 87
88 如果发送超时，将产生一个接收 88 如果发送超时，将产生一个接收，mad.status设置为ETIMEDOUT。否则，当一个
89 MAD被成功接收后，mad.status将是0。 89 MAD被成功接收后，mad.status将是0。
90 90
91 poll()/select()可以用来等待一个MAD 91 poll()/select()可以用来等待一个MAD可以被读取。
92 92
93 poll()/select()可以用来等待，直到 93 poll()/select()可以用来等待，直到可以读取一个MAD。
94 94
95 发送MADs 95 发送MADs
96 ======== 96 ========
97 97
98 MADs是用write()发送的。发送的代理 98 MADs是用write()发送的。发送的代理ID应该填入MAD的id字段，目的地LID应该
99 填入lid字段，以此类推。发送端 99 填入lid字段，以此类推。发送端确实支持RMPP，所以可以发送任意长度的MAD。
100 比如说:: 100 比如说::
101 101
102 struct ib_user_mad *mad; 102 struct ib_user_mad *mad;
103 103
104 mad = malloc(sizeof *mad + mad_length) 104 mad = malloc(sizeof *mad + mad_length);
105 105
106 /* fill in mad->data */ 106 /* fill in mad->data */
107 107
108 mad->hdr.id = my_agent; /* req 108 mad->hdr.id = my_agent; /* req.id from agent registration */
109 mad->hdr.lid = my_dest; /* in 109 mad->hdr.lid = my_dest; /* in network byte order... */
110 /* etc. */ 110 /* etc. */
111 111
112 ret = write(fd, &mad, sizeof *mad + ma 112 ret = write(fd, &mad, sizeof *mad + mad_length);
113 if (ret != sizeof *mad + mad_length) 113 if (ret != sizeof *mad + mad_length)
114 perror("write"); 114 perror("write");
115 115
116 交换IDs 116 交换IDs
117 ======= 117 =======
118 118
119 umad设备的用户可以在发送的MAD中 119 umad设备的用户可以在发送的MAD中使用交换ID字段的低32位（也就是网络字节顺序中
120 最小有效的一半字段）来匹配请 120 最小有效的一半字段）来匹配请求/响应对。上面的32位是保留给内核使用的，在发送
121 MAD之前会被改写。 121 MAD之前会被改写。
122 122
123 P_Key索引处理 123 P_Key索引处理
124 ============= 124 =============
125 125
126 旧的ib_umad接口不允许为发送的MAD 126 旧的ib_umad接口不允许为发送的MAD设置P_Key索引，也没有提供获取接收的MAD的
127 P_Key索引的方法。一个带有pkey_inde 127 P_Key索引的方法。一个带有pkey_index成员的struct ib_user_mad_hdr的新布局已
128 经被定义；然而，为了保持与旧 128 经被定义；然而，为了保持与旧的应用程序的二进制兼容性，除非在文件描述符被用于
129 其他用途之前调用IB_USER_MAD_ENABLE_P 129 其他用途之前调用IB_USER_MAD_ENABLE_PKEY或IB_USER_MAD_REGISTER_AGENT2 ioctl
130 之一，否则不会使用这种新布局 130 之一，否则不会使用这种新布局。
131 131
132 在2008年9月，IB_USER_MAD_ABI_VERSION将 132 在2008年9月，IB_USER_MAD_ABI_VERSION将被增加到6，默认使用新的ib_user_mad_hdr
133 结构布局，并且IB_USER_MAD_ENABLE_PKEY 133 结构布局，并且IB_USER_MAD_ENABLE_PKEY ioctl将被删除。
134 134
135 设置IsSM功能位 135 设置IsSM功能位
136 ============== 136 ==============
137 137
138 要为一个端口设置IsSM功能位，只 138 要为一个端口设置IsSM功能位，只需打开相应的issm设备文件。如果IsSM位已经被设置，那
139 么打开调用将阻塞，直到该位被 139 么打开调用将阻塞，直到该位被清除（或者如果O_NONBLOCK标志被传递给open()，则立即返
140 回，errno设置为EAGAIN）。当issm文 140 回，errno设置为EAGAIN）。当issm文件被关闭时，IsSM位将被清除。在issm文件上不能进
141 行任何读、写或其他操作。 141 行任何读、写或其他操作。
142 142
143 /dev文件 143 /dev文件
144 ======== 144 ========
145 145
146 为了用 udev自动创建相应的字符设 146 为了用 udev自动创建相应的字符设备文件，一个类似::
147 147
148 KERNEL=="umad*", NAME="infiniband/%k" 148 KERNEL=="umad*", NAME="infiniband/%k"
149 KERNEL=="issm*", NAME="infiniband/%k" 149 KERNEL=="issm*", NAME="infiniband/%k"
150 150
151 的规则可以被使用。它将创建节 151 的规则可以被使用。它将创建节点的名字::
152 152
153 /dev/infiniband/umad0 153 /dev/infiniband/umad0
154 /dev/infiniband/issm0 154 /dev/infiniband/issm0
155 155
156 为第一个端口，以此类推。与这 156 为第一个端口，以此类推。与这些设备相关的infiniband设备和端口可以从以下文件中确定::
157 157
158 /sys/class/infiniband_mad/umad0/ibdev 158 /sys/class/infiniband_mad/umad0/ibdev
159 /sys/class/infiniband_mad/umad0/port 159 /sys/class/infiniband_mad/umad0/port
160 160
161 和:: 161 和::
162 162
163 /sys/class/infiniband_mad/issm0/ibdev 163 /sys/class/infiniband_mad/issm0/ibdev
164 /sys/class/infiniband_mad/issm0/port 164 /sys/class/infiniband_mad/issm0/port
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.