1 ====================
2 Userspace MAD access
3 ====================
4
5 Device files
6 ============
7
8 Each port of each InfiniBand device has a "u
9 "issm" device attached. For example, a two-
10 umad devices and two issm devices, while a s
11 device of each type (for switch port 0).
12
13 Creating MAD agents
14 ===================
15
16 A MAD agent can be created by filling in a s
17 and then calling the IB_USER_MAD_REGISTER_AG
18 descriptor for the appropriate device file.
19 request succeeds, a 32-bit id will be return
20 For example::
21
22 struct ib_user_mad_reg_req req = { /*
23 ret = ioctl(fd, IB_USER_MAD_REGISTER_A
24 if (!ret)
25 my_agent = req.id;
26 else
27 perror("agent register");
28
29 Agents can be unregistered with the IB_USER_
30 ioctl. Also, all agents registered through
31 be unregistered when the descriptor is close
32
33 2014
34 a new registration ioctl is now provide
35 fields to be provided during registrati
36 Users of this registration call are imp
37 pkey_index (see below).
38
39 Receiving MADs
40 ==============
41
42 MADs are received using read(). The receive
43 RMPP. The buffer passed to read() must be at
44 struct ib_user_mad + 256 bytes. For example:
45
46 If the buffer passed is not large enough to
47 MAD (RMPP), the errno is set to ENOSPC and t
48 buffer needed is set in mad.length.
49
50 Example for normal MAD (non RMPP) reads::
51
52 struct ib_user_mad *mad;
53 mad = malloc(sizeof *mad + 256);
54 ret = read(fd, mad, sizeof *mad + 256)
55 if (ret != sizeof mad + 256) {
56 perror("read");
57 free(mad);
58 }
59
60 Example for RMPP reads::
61
62 struct ib_user_mad *mad;
63 mad = malloc(sizeof *mad + 256);
64 ret = read(fd, mad, sizeof *mad + 256)
65 if (ret == -ENOSPC)) {
66 length = mad.length;
67 free(mad);
68 mad = malloc(sizeof *mad + len
69 ret = read(fd, mad, sizeof *ma
70 }
71 if (ret < 0) {
72 perror("read");
73 free(mad);
74 }
75
76 In addition to the actual MAD contents, the
77 fields will be filled in with information on
78 example, the remote LID will be in mad.lid.
79
80 If a send times out, a receive will be gener
81 to ETIMEDOUT. Otherwise when a MAD has been
82 mad.status will be 0.
83
84 poll()/select() may be used to wait until a
85
86 Sending MADs
87 ============
88
89 MADs are sent using write(). The agent ID f
90 filled into the id field of the MAD, the des
91 filled into the lid field, and so on. The s
92 RMPP so arbitrary length MAD can be sent. Fo
93
94 struct ib_user_mad *mad;
95
96 mad = malloc(sizeof *mad + mad_length)
97
98 /* fill in mad->data */
99
100 mad->hdr.id = my_agent; /* req
101 mad->hdr.lid = my_dest; /* in
102 /* etc. */
103
104 ret = write(fd, &mad, sizeof *mad + ma
105 if (ret != sizeof *mad + mad_length)
106 perror("write");
107
108 Transaction IDs
109 ===============
110
111 Users of the umad devices can use the lower
112 transaction ID field (that is, the least sig
113 field in network byte order) in MADs being s
114 request/response pairs. The upper 32 bits a
115 the kernel and will be overwritten before a
116
117 P_Key Index Handling
118 ====================
119
120 The old ib_umad interface did not allow sett
121 MADs that are sent and did not provide a way
122 index of received MADs. A new layout for st
123 with a pkey_index member has been defined; h
124 compatibility with older applications, this
125 unless one of IB_USER_MAD_ENABLE_PKEY or IB_
126 are called before a file descriptor is used
127
128 In September 2008, the IB_USER_MAD_ABI_VERSI
129 to 6, the new layout of struct ib_user_mad_h
130 default, and the IB_USER_MAD_ENABLE_PKEY ioc
131
132 Setting IsSM Capability Bit
133 ===========================
134
135 To set the IsSM capability bit for a port, s
136 corresponding issm device file. If the IsSM
137 then the open call will block until the bit
138 immediately with errno set to EAGAIN if the
139 passed to open()). The IsSM bit will be cle
140 is closed. No read, write or other operatio
141 the issm file.
142
143 /dev files
144 ==========
145
146 To create the appropriate character device f
147 udev, a rule like::
148
149 KERNEL=="umad*", NAME="infiniband/%k"
150 KERNEL=="issm*", NAME="infiniband/%k"
151
152 can be used. This will create device nodes
153
154 /dev/infiniband/umad0
155 /dev/infiniband/issm0
156
157 for the first port, and so on. The InfiniBa
158 associated with these devices can be determi
159
160 /sys/class/infiniband_mad/umad0/ibdev
161 /sys/class/infiniband_mad/umad0/port
162
163 and::
164
165 /sys/class/infiniband_mad/issm0/ibdev
166 /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.