1mlx5dv_wr_set_mkey_sig_block(3) mlx5dv_wr_set_mkey_sig_block(3)
2
6 mlx5dv_wr_set_mkey_sig_block - Configure a MKEY for block signature
7 (data integrity) operation.
8
10 #include <infiniband/mlx5dv.h>
11 static inline void mlx5dv_wr_set_mkey_sig_block(struct mlx5dv_qp_ex *mqp,
13 const struct mlx5dv_sig_block_attr *attr)
14
16 Configure a MKEY with block-level data protection properties. With
17 this, the device can add/modify/strip/validate integrity fields per
18 block when transmitting data from memory to network and when receiving
19 data from network to memory.
20 This setter can be optionally called after a MKEY configuration work
22 request posting has started using mlx5dv_wr_mkey_configure(3). Config‐
23 uring block signature properties to a MKEY is done by describing what
24 kind of signature is required (or expected) in two domains: the wire
25 domain and the memory domain.
26 The MKEY represents a virtually contiguous memory, by configuring a
28 layout to it. The memory signature domain describes whether data in
29 this virtually contiguous memory includes integrity fields, and if so,
30 what kind and what block size.
31 The wire signature domain describes the same kind of properties for the
33 data as it is seen on the wire. Now, depending on the actual operation
34 that happens (TX or RX), the device will do the “right thing” based on
35 the signature configurations of the two domains.
36 Example 1:
38 Memory signature domain is configured for CRC32 every 512B block.
39 Wire signature domain is configured for no signature.
41 A SEND is issued using the MKEY as a local key.
43 Result: device will gather the data with the CRC32 fields from the MKEY
45 (using whatever layout configured to the MKEY to locate the actual mem‐
46 ory), validate each CRC32 against the previous 512 bytes of data, strip
47 the CRC32 field, and transmit only 512 bytes of data to the wire.
48 Example 1.1:
50 Same as above, but a RECV is issued with the same key, and RX happens.
51 Result: device will receive the data from the wire, scatter it to the
53 MKEY (using whatever layout configured to the MKEY to locate the actual
54 memory), generating and scattering additional CRC32 field after every
55 512 bytes that are scattered.
56 Example 2:
58 Memory signature domain is configured for no signature.
59 Wire signature domain is configured for T10DIF every 4K block.
61 The MKEY is sent to a remote node that issues a RDMA_READ to this MKEY.
63 Result: device will gather the data from the MKEY (using whatever lay‐
65 out configured to the MKEY to locate the actual memory), transmit it to
66 the wire while generating an additional T10DIF field every 4K of data.
67 Example 2.1:
69 Same as above, but remote node issues a RDMA_WRITE to this MKEY.
70 Result: Device will receive the data from the wire, validate each
72 T10DIF field against the previous 4K of data, strip the T10DIF field,
73 and scatter the data alone to the MKEY (using whatever layout config‐
74 ured to the MKEY to locate the actual memory).
75
77 mqp
78 The QP where an MKEY configuration work request was created by
80 mlx5dv_wr_mkey_configure().
82 attr Block signature attributes to set for the MKEY.
84 Block signature attributes
86 Block signature attributes describe the input and output data struc‐
87 tures in memory and wire domains.
88 struct mlx5dv_sig_block_attr {
90 const struct mlx5dv_sig_block_domain *mem;
91 const struct mlx5dv_sig_block_domain *wire;
92 uint32_t flags;
93 uint8_t check_mask;
94 uint8_t copy_mask;
95 uint64_t comp_mask;
96 };
97 mem A pointer to the signature configuration for the memory domain
99 or NULL if the domain does not have a signature.
100 wire A pointer to the signature configuration for the wire domain or
102 NULL if the domain does not have a signature.
103 flags A bitwise OR of the various values described below.
105 MLX5DV_SIG_BLOCK_ATTR_FLAG_COPY_MASK
107 If the bit is not set then copy_mask is ignored. See de‐
108 tails in the copy_mask description.
109 check_mask
111 Each bit of check_mask corresponds to a byte of the signature
112 field in input domain. Byte of the input signature is checked
113 if corresponding bit in check_mask is set. Bits not relevant to
114 the signature type are ignored.
115 Layout of check_mask.
117 check_mask 7 6 5 4 3 2 1 0
119 (bits)
120 ─────────────────────────────────────────────────────────────────────────────────────────
121 T10-DIF GUARD[1] GUARD[0] APP[1] APP[0] REF[3] REF[2] REF[1] REF[0]
122 (bytes)
123 CRC32C/CRC32 3 2 1 0
124 (bytes)
125 CRC64_XP10 7 6 5 4 3 2 1 0
126 (bytes)
127 Common used masks are defined in enum mlx5dv_sig_mask. Other
129 masks are also supported. Follow the above table to define a
130 custom mask. For example, this can be useful for the applica‐
131 tion tag field of the T10DIF signature. Using the application
132 tag is out of the scope of the T10DIF specification and depends
133 on the implementation. check_mask allows validating a part of
134 the application tag if needed.
135 copy_mask
137 A mask to specify what part of the signature is copied from the
138 source domain to the destination domain. The copy mask is usu‐
139 ally calculated automatically. The signature is copied if the
140 same signature type is configurted on both domains. The parts
141 of the T10-DIF are compared and handled independetly.
142 If MLX5DV_SIG_BLOCK_ATTR_FLAG_COPY_MASK is set the copy_mask at‐
144 tribute overrides the calculated value of the copy mask. Other‐
145 wise, copy_mask is ignored.
146 Each bit of copy_mask corresponds to a byte of the signature
148 field. If corresponding bit in copy_mask is set, byte of the
149 signature is copied from the input domain to the output domain.
150 Calculation according to the output domain configuration is not
151 performed in this case. Bits not relevant to the signature type
152 are ignored. copy_mask may be used only if input and output do‐
153 mains have the same structure, i.e. same block size and signa‐
154 ture type. The MKEY configuration will fail if
155 MLX5DV_SIG_BLOCK_ATTR_FLAG_COPY_MASK is set but the domains have
156 different signature structures.
157 The predefined masks are available in enum mlx5dv_sig_mask. It
159 is also supported to specify a user-defined mask. Follow the
160 table in check_mask description to define a custom mask.
161 copy_mask can be useful when some bytes of the signature are not
163 known in advance, hence can’t be checked, but shall be pre‐
164 served. In this case corresponding bits should be cleared in
165 check_mask and set in copy_mask.
166 comp_mask
168 Reserved for future extension, must be 0 now.
169 Block signature domain
171 struct mlx5dv_sig_block_domain {
172 enum mlx5dv_sig_type sig_type;
173 union {
174 const struct mlx5dv_sig_t10dif *dif;
175 const struct mlx5dv_sig_crc *crc;
176 } sig;
177 enum mlx5dv_block_size block_size;
178 uint64_t comp_mask;
179 };
180 sig_type
182 The signature type for this domain, one of the following
183 MLX5DV_SIG_TYPE_T10DIF
185 The block-level data protection defined in the T10 speci‐
186 fications (T10 SBC-3).
187 MLX5DV_SIG_TYPE_CRC
189 The block-level data protection based on cyclic redundan‐
190 cy check (CRC). The specific type of CRC is defined in
191 sig.
192 sig Depending on sig_type, this is the per signature type specific
194 configuration.
195 block_size
197 The block size for this domain, one of enum
198 mlx5dv_sig_block_size.
199 comp_mask
201 Reserved for future extension, must be 0 now.
202 CRC signature
204 struct mlx5dv_sig_crc {
205 enum mlx5dv_sig_crc_type type;
206 uint64_t seed;
207 };
208 type The specific CRC type, one of the following.
210 MLX5DV_SIG_CRC_TYPE_CRC32
212 CRC32 signature is created by calculating a 32-bit CRC
213 defined in Fibre Channel Physical and Signaling Interface
214 (FC-PH), ANSI X3.230:1994.
215 MLX5DV_SIG_CRC_TYPE_CRC32C
217 CRC32C signature is created by calculating a 32-bit CRC
218 called the Castagnoli CRC, defined in the Internet Small
219 Computer Systems Interface (iSCSI) rfc3720.
220 MLX5DV_SIG_CRC_TYPE_CRC64_XP10
222 CRC64_XP10 signature is created by calculating a 64-bit
223 CRC defined in Microsoft XP10 compression standard.
224 seed A seed for the CRC calculation per block. Bits not relevant to
226 the CRC type are ignored. For example, all bits are used for
227 CRC64_XP10, but only the 32 least significant bits are used for
228 CRC32/CRC32C.
229 Only the following values are supported as a seed: CRC32/CRC32C
231 - 0, 0xFFFFFFFF(UINT32_MAX); CRC64_XP10 - 0,
232 0xFFFFFFFFFFFFFFFF(UINT64_MAX).
233 T10DIF signature
235 T10DIF signature is defined in the T10 specifications (T10 SBC-3) for
236 block-level data protection. The size of data block protected by
237 T10DIF must be modulo 8bytes as required in the T10DIF specifications.
238 Note that when setting the initial LBA value to ref_tag, it should be
239 the value of the first block to be transmitted.
240 struct mlx5dv_sig_t10dif {
242 enum mlx5dv_sig_t10dif_bg_type bg_type;
243 uint16_t bg;
244 uint16_t app_tag;
245 uint32_t ref_tag;
246 uint16_t flags;
247 };
248 bg_type
250 The block guard type to be used, one of the following.
251 MLX5DV_SIG_T10DIF_CRC
253 Use CRC in the block guard field as required in the
254 T10DIF specifications.
255 MLX5DV_SIG_T10DIF_CSUM
257 Use IP checksum instead of CRC in the block guard field.
258 bg A seed for the block guard calculation per block.
260 The following values are supported as a seed: 0,
262 0xFFFF(UINT16_MAX).
263 app_tag
265 An application tag to generate or validate.
266 ref_tag
268 A reference tag to generate or validate.
269 flags Flags for the T10DIF attributes, one of the following.
271 MLX5DV_SIG_T10DIF_FLAG_REF_REMAP
273 Increment reference tag per block.
274 MLX5DV_SIG_T10DIF_FLAG_APP_ESCAPE
276 Do not check block guard if application tag is 0xFFFF.
277 MLX5DV_SIG_T10DIF_FLAG_APP_REF_ESCAPE
279 Do not check block guard if application tag is 0xFFFF and
280 reference tag is 0xFFFFFFFF.
281
283 This function does not return a value.
284 In case of error, user will be notified later when completing the DV
286 WRs chain.
287
289 A DEVX context should be opened by using mlx5dv_open_device(3).
290 MKEY must be created with MLX5DV_MKEY_INIT_ATTR_FLAGS_BLOCK_SIGNATURE
292 flag.
293 The last operation posted on the supplied QP should be
295 mlx5dv_wr_mkey_configure(3), or one of its related setters, and the op‐
296 eration must still be open (no doorbell issued).
297 In case of ibv_wr_complete() failure or calling to ibv_wr_abort(), the
299 MKey may be left in an unknown state. The next configuration of it
300 should not assume any previous state of the MKey, i.e. signature/crypto
301 should be re-configured or reset, as required. For example, assuming
302 mlx5dv_wr_set_mkey_sig_block() and then ibv_wr_abort() were called,
303 then on the next configuration of the MKey, if signature is not needed,
304 it should be reset using MLX5DV_MKEY_CONF_FLAG_RESET_SIG_ATTR.
305
307 mlx5dv_wr_mkey_configure(3), mlx5dv_create_mkey(3), mlx5dv_de‐
308 stroy_mkey(3)
309
311 Oren Duer <oren@nvidia.com>
312 Sergey Gorenko <sergeygo@nvidia.com>
314 mlx5dv_wr_set_mkey_sig_block(3)