Debian Codegraph @

src/nvme/util.h

raw
1 // SPDX-License-Identifier: LGPL-2.1-or-later
2 /*
3 * This file is part of libnvme.
4 * Copyright (c) 2020 Western Digital Corporation or its affiliates.
5 *
6 * Authors: Keith Busch <[email protected]>
7 * Chaitanya Kulkarni <[email protected]>
8 */
9 #ifndef _LIBNVME_UTIL_H
10 #define _LIBNVME_UTIL_H
11
12 #include <ifaddrs.h>
13
14 #include <nvme/types.h>
15
16 /**
17 * DOC: util.h
18 *
19 * libnvme utility functions
20 */
21
22 /**
23 * enum nvme_connect_err - nvme connect error codes
24 * @ENVME_CONNECT_RESOLVE: failed to resolve host
25 * @ENVME_CONNECT_ADDRFAM: unrecognized address family
26 * @ENVME_CONNECT_TRADDR: failed to get traddr
27 * @ENVME_CONNECT_TARG: need a transport (-t) argument
28 * @ENVME_CONNECT_AARG: need a address (-a) argument
29 * @ENVME_CONNECT_OPEN: failed to open nvme-fabrics device
30 * @ENVME_CONNECT_WRITE: failed to write to nvme-fabrics device
31 * @ENVME_CONNECT_READ: failed to read from nvme-fabrics device
32 * @ENVME_CONNECT_PARSE: failed to parse ctrl info
33 * @ENVME_CONNECT_INVAL_TR: invalid transport type
34 * @ENVME_CONNECT_LOOKUP_SUBSYS_NAME: failed to lookup subsystem name
35 * @ENVME_CONNECT_LOOKUP_SUBSYS: failed to lookup subsystem
36 * @ENVME_CONNECT_ALREADY: the connect attempt failed, already connected
37 * @ENVME_CONNECT_INVAL: invalid arguments/configuration
38 * @ENVME_CONNECT_ADDRINUSE: hostnqn already in use
39 * @ENVME_CONNECT_NODEV: invalid interface
40 * @ENVME_CONNECT_OPNOTSUPP: not supported
41 * @ENVME_CONNECT_CONNREFUSED: connection refused
42 * @ENVME_CONNECT_ADDRNOTAVAIL: cannot assign requested address
43 * @ENVME_CONNECT_IGNORED: connect attempt is ignored due to configuration
44 * @ENVME_CONNECT_NOKEY: the TLS key is missing
45 */
46 enum nvme_connect_err {
47 ENVME_CONNECT_RESOLVE = 1000,
48 ENVME_CONNECT_ADDRFAM,
49 ENVME_CONNECT_TRADDR,
50 ENVME_CONNECT_TARG,
51 ENVME_CONNECT_AARG,
52 ENVME_CONNECT_OPEN,
53 ENVME_CONNECT_WRITE,
54 ENVME_CONNECT_READ,
55 ENVME_CONNECT_PARSE,
56 ENVME_CONNECT_INVAL_TR,
57 ENVME_CONNECT_LOOKUP_SUBSYS_NAME,
58 ENVME_CONNECT_LOOKUP_SUBSYS,
59 ENVME_CONNECT_ALREADY,
60 ENVME_CONNECT_INVAL,
61 ENVME_CONNECT_ADDRINUSE,
62 ENVME_CONNECT_NODEV,
63 ENVME_CONNECT_OPNOTSUPP,
64 ENVME_CONNECT_CONNREFUSED,
65 ENVME_CONNECT_ADDRNOTAVAIL,
66 ENVME_CONNECT_IGNORED,
67 ENVME_CONNECT_NOKEY,
68 };
69
70 /**
71 * nvme_status_to_errno() - Converts nvme return status to errno
72 * @status: Return status from an nvme passthrough command
73 * @fabrics: Set to true if &status is to a fabrics target.
74 *
75 * Return: An errno representing the nvme status if it is an nvme status field,
76 * or unchanged status is < 0 since errno is already set.
77 */
78 __u8 nvme_status_to_errno(int status, bool fabrics);
79
80 /**
81 * nvme_status_to_string() - Returns string describing nvme return status.
82 * @status: Return status from an nvme passthrough command
83 * @fabrics: Set to true if &status is to a fabrics target.
84 *
85 * Return: String representation of the nvme status if it is an nvme status field,
86 * or a standard errno string if status is < 0.
87 */
88 const char *nvme_status_to_string(int status, bool fabrics);
89
90 /**
91 * nvme_errno_to_string() - Returns string describing nvme connect failures
92 * @err: Returned error code from nvme_add_ctrl()
93 *
94 * Return: String representation of the nvme connect error codes
95 */
96 const char *nvme_errno_to_string(int err);
97
98 /**
99 * nvme_init_ctrl_list() - Initialize an nvme_ctrl_list structure from an array.
100 * @cntlist: The controller list structure to initialize
101 * @num_ctrls: The number of controllers in the array, &ctrlist.
102 * @ctrlist: An array of controller identifiers in CPU native endian.
103 *
104 * This is intended to be used with any command that takes a controller list
105 * argument. See nvme_ns_attach_ctrls() and nvme_ns_detach().
106 */
107 void nvme_init_ctrl_list(struct nvme_ctrl_list *cntlist, __u16 num_ctrls,
108 __u16 *ctrlist);
109
110 /**
111 * nvme_init_dsm_range() - Constructs a data set range structure
112 * @dsm: DSM range array
113 * @ctx_attrs: Array of context attributes
114 * @llbas: Array of length in logical blocks
115 * @slbas: Array of starting logical blocks
116 * @nr_ranges: The size of the dsm arrays
117 *
118 * Each array must be the same size of size 'nr_ranges'. This is intended to be
119 * used with constructing a payload for nvme_dsm().
120 *
121 * Return: The nvme command status if a response was received or -errno
122 * otherwise.
123 */
124 void nvme_init_dsm_range(struct nvme_dsm_range *dsm, __u32 *ctx_attrs,
125 __u32 *llbas, __u64 *slbas, __u16 nr_ranges);
126
127 /**
128 * nvme_init_copy_range() - Constructs a copy range structure
129 * @copy: Copy range array
130 * @nlbs: Number of logical blocks
131 * @slbas: Starting LBA
132 * @eilbrts: Expected initial logical block reference tag
133 * @elbatms: Expected logical block application tag mask
134 * @elbats: Expected logical block application tag
135 * @nr: Number of descriptors to construct
136 */
137 void nvme_init_copy_range(struct nvme_copy_range *copy, __u16 *nlbs,
138 __u64 *slbas, __u32 *eilbrts, __u32 *elbatms,
139 __u32 *elbats, __u16 nr);
140
141 /**
142 * nvme_init_copy_range_f1() - Constructs a copy range f1 structure
143 * @copy: Copy range array
144 * @nlbs: Number of logical blocks
145 * @slbas: Starting LBA
146 * @eilbrts: Expected initial logical block reference tag
147 * @elbatms: Expected logical block application tag mask
148 * @elbats: Expected logical block application tag
149 * @nr: Number of descriptors to construct
150 */
151 void nvme_init_copy_range_f1(struct nvme_copy_range_f1 *copy, __u16 *nlbs,
152 __u64 *slbas, __u64 *eilbrts, __u32 *elbatms,
153 __u32 *elbats, __u16 nr);
154
155 /**
156 * nvme_init_copy_range_f2() - Constructs a copy range f2 structure
157 * @copy: Copy range array
158 * @snsids: Source namespace identifier
159 * @nlbs: Number of logical blocks
160 * @slbas: Starting LBA
161 * @sopts: Source options
162 * @eilbrts: Expected initial logical block reference tag
163 * @elbatms: Expected logical block application tag mask
164 * @elbats: Expected logical block application tag
165 * @nr: Number of descriptors to construct
166 */
167 void nvme_init_copy_range_f2(struct nvme_copy_range_f2 *copy, __u32 *snsids,
168 __u16 *nlbs, __u64 *slbas, __u16 *sopts,
169 __u32 *eilbrts, __u32 *elbatms, __u32 *elbats,
170 __u16 nr);
171
172 /**
173 * nvme_init_copy_range_f3() - Constructs a copy range f3 structure
174 * @copy: Copy range array
175 * @snsids: Source namespace identifier
176 * @nlbs: Number of logical blocks
177 * @slbas: Starting LBA
178 * @sopts: Source options
179 * @eilbrts: Expected initial logical block reference tag
180 * @elbatms: Expected logical block application tag mask
181 * @elbats: Expected logical block application tag
182 * @nr: Number of descriptors to construct
183 */
184 void nvme_init_copy_range_f3(struct nvme_copy_range_f3 *copy, __u32 *snsids,
185 __u16 *nlbs, __u64 *slbas, __u16 *sopts,
186 __u64 *eilbrts, __u32 *elbatms, __u32 *elbats,
187 __u16 nr);
188
189 /**
190 * nvme_get_feature_length() - Retreive the command payload length for a
191 * specific feature identifier
192 * @fid: Feature identifier, see &enum nvme_features_id.
193 * @cdw11: The cdw11 value may affect the transfer (only known fid is
194 * %NVME_FEAT_FID_HOST_ID)
195 * @len: On success, set to this features payload length in bytes.
196 *
197 * Return: 0 on success, -1 with errno set to EINVAL if the function did not
198 * recognize &fid.
199 */
200 int nvme_get_feature_length(int fid, __u32 cdw11, __u32 *len);
201
202 /**
203 * nvme_get_feature_length2() - Retreive the command payload length for a
204 * specific feature identifier
205 * @fid: Feature identifier, see &enum nvme_features_id.
206 * @cdw11: The cdw11 value may affect the transfer (only known fid is
207 * %NVME_FEAT_FID_HOST_ID)
208 * @dir: Data transfer direction: false - host to controller, true -
209 * controller to host may affect the transfer (only known fid is
210 * %NVME_FEAT_FID_HOST_MEM_BUF).
211 * @len: On success, set to this features payload length in bytes.
212 *
213 * Return: 0 on success, -1 with errno set to EINVAL if the function did not
214 * recognize &fid.
215 */
216 int nvme_get_feature_length2(int fid, __u32 cdw11, enum nvme_data_tfr dir,
217 __u32 *len);
218
219 /**
220 * nvme_get_directive_receive_length() - Get directive receive length
221 * @dtype: Directive type, see &enum nvme_directive_dtype
222 * @doper: Directive receive operation, see &enum nvme_directive_receive_doper
223 * @len: On success, set to this directives payload length in bytes.
224 *
225 * Return: 0 on success, -1 with errno set to EINVAL if the function did not
226 * recognize &dtype or &doper.
227 */
228 int nvme_get_directive_receive_length(enum nvme_directive_dtype dtype,
229 enum nvme_directive_receive_doper doper, __u32 *len);
230
231 #define NVME_FEAT_ARB_BURST(v) NVME_GET(v, FEAT_ARBITRATION_BURST)
232 #define NVME_FEAT_ARB_LPW(v) NVME_GET(v, FEAT_ARBITRATION_LPW)
233 #define NVME_FEAT_ARB_MPW(v) NVME_GET(v, FEAT_ARBITRATION_MPW)
234 #define NVME_FEAT_ARB_HPW(v) NVME_GET(v, FEAT_ARBITRATION_HPW)
235
236 static inline void nvme_feature_decode_arbitration(__u32 value, __u8 *ab,
237 __u8 *lpw, __u8 *mpw,
238 __u8 *hpw)
239 {
240 *ab = NVME_FEAT_ARB_BURST(value);
241 *lpw = NVME_FEAT_ARB_LPW(value);
242 *mpw = NVME_FEAT_ARB_MPW(value);
243 *hpw = NVME_FEAT_ARB_HPW(value);
244 };
245
246 #define NVME_FEAT_PM_PS(v) NVME_GET(v, FEAT_PWRMGMT_PS)
247 #define NVME_FEAT_PM_WH(v) NVME_GET(v, FEAT_PWRMGMT_WH)
248
249 static inline void nvme_feature_decode_power_mgmt(__u32 value, __u8 *ps,
250 __u8 *wh)
251 {
252 *ps = NVME_FEAT_PM_PS(value);
253 *wh = NVME_FEAT_PM_WH(value);
254 }
255
256 #define NVME_FEAT_LBAR_NR(v) NVME_GET(v, FEAT_LBAR_NR)
257
258 static inline void nvme_feature_decode_lba_range(__u32 value, __u8 *num)
259 {
260 *num = NVME_FEAT_LBAR_NR(value);
261 }
262
263 #define NVME_FEAT_TT_TMPTH(v) NVME_GET(v, FEAT_TT_TMPTH)
264 #define NVME_FEAT_TT_TMPSEL(v) NVME_GET(v, FEAT_TT_TMPSEL)
265 #define NVME_FEAT_TT_THSEL(v) NVME_GET(v, FEAT_TT_THSEL)
266 #define NVME_FEAT_TT_TMPTHH(v) NVME_GET(v, FEAT_TT_TMPTHH)
267
268 static inline void nvme_feature_decode_temp_threshold(__u32 value, __u16 *tmpth,
269 __u8 *tmpsel, __u8 *thsel,
270 __u8 *tmpthh)
271 {
272 *tmpth = NVME_FEAT_TT_TMPTH(value);
273 *tmpsel = NVME_FEAT_TT_TMPSEL(value);
274 *thsel = NVME_FEAT_TT_THSEL(value);
275 *tmpthh = NVME_FEAT_TT_TMPTHH(value);
276 }
277
278 #define NVME_FEAT_ER_TLER(v) NVME_GET(v, FEAT_ERROR_RECOVERY_TLER)
279 #define NVME_FEAT_ER_DULBE(v) NVME_GET(v, FEAT_ERROR_RECOVERY_DULBE)
280
281 static inline void nvme_feature_decode_error_recovery(__u32 value, __u16 *tler,
282 bool *dulbe)
283 {
284 *tler = NVME_FEAT_ER_TLER(value);
285 *dulbe = NVME_FEAT_ER_DULBE(value);
286 }
287
288 #define NVME_FEAT_VWC_WCE(v) NVME_GET(v, FEAT_VWC_WCE)
289
290 static inline void nvme_feature_decode_volatile_write_cache(__u32 value,
291 bool *wce)
292 {
293 *wce = NVME_FEAT_VWC_WCE(value);
294 }
295
296 #define NVME_FEAT_NRQS_NSQR(v) NVME_GET(v, FEAT_NRQS_NSQR)
297 #define NVME_FEAT_NRQS_NCQR(v) NVME_GET(v, FEAT_NRQS_NCQR)
298
299 static inline void nvme_feature_decode_number_of_queues(__u32 value,
300 __u16 *nsqr,
301 __u16 *ncqr)
302 {
303 *nsqr = NVME_FEAT_NRQS_NSQR(value);
304 *ncqr = NVME_FEAT_NRQS_NCQR(value);
305 }
306
307 #define NVME_FEAT_IRQC_THR(v) NVME_GET(v, FEAT_IRQC_THR)
308 #define NVME_FEAT_IRQC_TIME(v) NVME_GET(v, FEAT_IRQC_TIME)
309
310 static inline void nvme_feature_decode_interrupt_coalescing(__u32 value,
311 __u8 *thr,
312 __u8 *time)
313 {
314 *thr = NVME_FEAT_IRQC_THR(value);
315 *time = NVME_FEAT_IRQC_TIME(value);
316 }
317
318 #define NVME_FEAT_ICFG_IV(v) NVME_GET(v, FEAT_ICFG_IV)
319 #define NVME_FEAT_ICFG_CD(v) NVME_GET(v, FEAT_ICFG_CD)
320
321 static inline void nvme_feature_decode_interrupt_config(__u32 value, __u16 *iv,
322 bool *cd)
323 {
324 *iv = NVME_FEAT_ICFG_IV(value);
325 *cd = NVME_FEAT_ICFG_CD(value);
326 }
327
328 #define NVME_FEAT_WA_DN(v) NVME_GET(v, FEAT_WA_DN)
329
330 static inline void nvme_feature_decode_write_atomicity(__u32 value, bool *dn)
331 {
332 *dn = NVME_FEAT_WA_DN(value);
333 }
334
335 #define NVME_FEAT_AE_SMART(v) NVME_GET(v, FEAT_AE_SMART)
336 #define NVME_FEAT_AE_NAN(v) NVME_GET(v, FEAT_AE_NAN)
337 #define NVME_FEAT_AE_FW(v) NVME_GET(v, FEAT_AE_FW)
338 #define NVME_FEAT_AE_TELEM(v) NVME_GET(v, FEAT_AE_TELEM)
339 #define NVME_FEAT_AE_ANA(v) NVME_GET(v, FEAT_AE_ANA)
340 #define NVME_FEAT_AE_PLA(v) NVME_GET(v, FEAT_AE_PLA)
341 #define NVME_FEAT_AE_LBAS(v) NVME_GET(v, FEAT_AE_LBAS)
342 #define NVME_FEAT_AE_EGA(v) NVME_GET(v, FEAT_AE_EGA)
343 #define NVME_FEAT_AE_NNSSHDN(v) NVME_GET(v, FEAT_AE_NNSSHDN)
344 #define NVME_FEAT_AE_TTHRY(v) NVME_GET(v, FEAT_AE_TTHRY)
345 #define NVME_FEAT_AE_RASSN(v) NVME_GET(v, FEAT_AE_RASSN)
346 #define NVME_FEAT_AE_RGRP0(v) NVME_GET(v, FEAT_AE_RGRP0)
347 #define NVME_FEAT_AE_ANSAN(v) NVME_GET(v, FEAT_AE_ANSAN)
348 #define NVME_FEAT_AE_ZDCN(v) NVME_GET(v, FEAT_AE_ZDCN)
349 #define NVME_FEAT_AE_PMDRLPCN(v) NVME_GET(v, FEAT_AE_PMDRLPCN)
350 #define NVME_FEAT_AE_ADLPCN(v) NVME_GET(v, FEAT_AE_ADLPCN)
351 #define NVME_FEAT_AE_HDLPCN(v) NVME_GET(v, FEAT_AE_HDLPCN)
352 #define NVME_FEAT_AE_DLPCN(v) NVME_GET(v, FEAT_AE_DLPCN)
353
354 static inline void nvme_feature_decode_async_event_config(__u32 value,
355 __u8 *smart, bool *nan, bool *fw, bool *telem,
356 bool *ana, bool *pla, bool *lbas, bool *ega)
357 {
358 *smart = NVME_FEAT_AE_SMART(value);
359 *nan = NVME_FEAT_AE_NAN(value);
360 *fw = NVME_FEAT_AE_FW(value);
361 *telem = NVME_FEAT_AE_TELEM(value);
362 *ana = NVME_FEAT_AE_ANA(value);
363 *pla = NVME_FEAT_AE_PLA(value);
364 *lbas = NVME_FEAT_AE_LBAS(value);
365 *ega = NVME_FEAT_AE_EGA(value);
366 }
367
368 #define NVME_FEAT_APST_APSTE(v) NVME_GET(v, FEAT_APST_APSTE)
369
370 static inline void nvme_feature_decode_auto_power_state(__u32 value,
371 bool *apste)
372 {
373 *apste = NVME_FEAT_APST_APSTE(value);
374 }
375
376 #define NVME_FEAT_HMEM_EHM(v) NVME_GET(v, FEAT_HMEM_EHM)
377
378 static inline void nvme_feature_decode_host_memory_buffer(__u32 value, bool *ehm)
379 {
380 *ehm = NVME_FEAT_HMEM_EHM(value);
381 }
382
383 #define NVME_FEAT_HCTM_TMT2(v) NVME_GET(v, FEAT_HCTM_TMT2)
384 #define NVME_FEAT_HCTM_TMT1(v) NVME_GET(v, FEAT_HCTM_TMT1)
385
386 static inline void nvme_feature_decode_host_thermal_mgmt(__u32 value,
387 __u16 *tmt2,
388 __u16 *tmt1)
389 {
390 *tmt2 = NVME_FEAT_HCTM_TMT2(value);
391 *tmt1 = NVME_FEAT_HCTM_TMT1(value);
392 }
393
394 #define NVME_FEAT_NOPS_NOPPME(v) NVME_GET(v, FEAT_NOPS_NOPPME)
395
396 static inline void nvme_feature_decode_non_op_power_config(__u32 value,
397 bool *noppme)
398 {
399 *noppme = NVME_FEAT_NOPS_NOPPME(value);
400 }
401
402 #define NVME_FEAT_RRL_RRL(v) NVME_GET(v, FEAT_RRL_RRL)
403
404 static inline void nvme_feature_decode_read_recovery_level_config(__u32 value,
405 __u8 *rrl)
406 {
407 *rrl = NVME_FEAT_RRL_RRL(value);
408 }
409
410 #define NVME_FEAT_PLM_PLME(v) NVME_GET(v, FEAT_PLM_PLME)
411
412 static inline void nvme_feature_decode_predictable_latency_mode_config(__u32 value,
413 bool *plme)
414 {
415 *plme = NVME_FEAT_PLM_PLME(value);
416 }
417
418 #define NVME_FEAT_PLMW_WS(v) NVME_GET(v, FEAT_PLMW_WS)
419
420 static inline void nvme_feature_decode_predictable_latency_mode_window(__u32 value,
421 __u8 *ws)
422 {
423 *ws = NVME_FEAT_PLMW_WS(value);
424 }
425
426 #define NVME_FEAT_LBAS_LSIRI(v) NVME_GET(v, FEAT_LBAS_LSIRI)
427 #define NVME_FEAT_LBAS_LSIPI(v) NVME_GET(v, FEAT_LBAS_LSIPI)
428
429 static inline void nvme_feature_decode_lba_status_attributes(__u32 value,
430 __u16 *lsiri,
431 __u16 *lsipi)
432 {
433 *lsiri = NVME_FEAT_LBAS_LSIRI(value);
434 *lsipi = NVME_FEAT_LBAS_LSIPI(value);
435 }
436
437 #define NVME_FEAT_SC_NODRM(v) NVME_GET(v, FEAT_SC_NODRM)
438
439 static inline void nvme_feature_decode_sanitize_config(__u32 value, bool *nodrm)
440 {
441 *nodrm = NVME_FEAT_SC_NODRM(value);
442 }
443
444 #define NVME_FEAT_EG_ENDGID(v) NVME_GET(v, FEAT_EG_ENDGID)
445 #define NVME_FEAT_EG_EGCW(v) NVME_GET(v, FEAT_EG_EGCW)
446
447 static inline void nvme_feature_decode_endurance_group_event_config(__u32 value,
448 __u16 *endgid, __u8 *endgcw)
449 {
450 *endgid = NVME_FEAT_EG_ENDGID(value);
451 *endgcw = NVME_FEAT_EG_EGCW(value);
452 }
453
454 #define NVME_FEAT_PERFC_ATTRI(v) NVME_GET(v, FEAT_PERFC_ATTRI)
455 #define NVME_FEAT_PERFC_RVSPA(v) NVME_GET(v, FEAT_PERFC_RVSPA)
456
457 static inline void nvme_feature_decode_perf_characteristics(__u32 value, __u8 *attri, bool *rvspa)
458 {
459 *attri = NVME_FEAT_PERFC_ATTRI(value);
460 *rvspa = NVME_FEAT_PERFC_RVSPA(value);
461 }
462
463 #define NVME_FEAT_SPM_PBSLC(v) NVME_GET(v, FEAT_SPM_PBSLC)
464
465 static inline void nvme_feature_decode_software_progress_marker(__u32 value,
466 __u8 *pbslc)
467 {
468 *pbslc = NVME_FEAT_SPM_PBSLC(value);
469 }
470
471 #define NVME_FEAT_HOSTID_EXHID(v) NVME_GET(v, FEAT_HOSTID_EXHID)
472
473 static inline void nvme_feature_decode_host_identifier(__u32 value, bool *exhid)
474 {
475 *exhid = NVME_FEAT_HOSTID_EXHID(value);
476 }
477
478 #define NVME_FEAT_RM_REGPRE(v) NVME_GET(v, FEAT_RM_REGPRE)
479 #define NVME_FEAT_RM_RESREL(v) NVME_GET(v, FEAT_RM_RESREL)
480 #define NVME_FEAT_RM_RESPRE(v) NVME_GET(v, FEAT_RM_RESPRE)
481
482 static inline void nvme_feature_decode_reservation_notification(__u32 value,
483 bool *regpre,
484 bool *resrel,
485 bool *respre)
486 {
487 *regpre = NVME_FEAT_RM_REGPRE(value);
488 *resrel = NVME_FEAT_RM_RESREL(value);
489 *respre = NVME_FEAT_RM_RESPRE(value);
490 }
491
492 #define NVME_FEAT_RP_PTPL(v) NVME_GET(v, FEAT_RP_PTPL)
493
494 static inline void nvme_feature_decode_reservation_persistance(__u32 value,
495 bool *ptpl)
496 {
497 *ptpl = NVME_FEAT_RP_PTPL(value);
498 }
499
500 #define NVME_FEAT_WP_WPS(v) NVME_GET(v, FEAT_WP_WPS)
501
502 static inline void nvme_feature_decode_namespace_write_protect(__u32 value,
503 __u8 *wps)
504 {
505 *wps = NVME_FEAT_WP_WPS(value);
506 }
507
508 #define NVME_FEAT_BPWPC_BP0WPS(v) NVME_GET(v, FEAT_BPWPC_BP0WPS)
509 #define NVME_FEAT_BPWPC_BP1WPS(v) NVME_GET(v, FEAT_BPWPC_BP1WPS)
510
511 static inline void nvme_id_ns_flbas_to_lbaf_inuse(__u8 flbas, __u8 *lbaf_inuse)
512 {
513 *lbaf_inuse = ((NVME_FLBAS_HIGHER(flbas) << 4) |
514 NVME_FLBAS_LOWER(flbas));
515 }
516
517 struct nvme_root;
518
519 char *hostname2traddr(struct nvme_root *r, const char *traddr);
520
521 /**
522 * get_entity_name - Get Entity Name (ENAME).
523 * @buffer: The buffer where the ENAME will be saved as an ASCII string.
524 * @bufsz: The size of @buffer.
525 *
526 * Per TP8010, ENAME is defined as the name associated with the host (i.e.
527 * hostname).
528 *
529 * Return: Number of characters copied to @buffer.
530 */
531 size_t get_entity_name(char *buffer, size_t bufsz);
532
533 /**
534 * get_entity_version - Get Entity Version (EVER).
535 * @buffer: The buffer where the EVER will be saved as an ASCII string.
536 * @bufsz: The size of @buffer.
537 *
538 * EVER is defined as the operating system name and version as an ASCII
539 * string. This function reads different files from the file system and
540 * builds a string as follows: [os type] [os release] [distro release]
541 *
542 * E.g. "Linux 5.17.0-rc1 SLES 15.4"
543 *
544 * Return: Number of characters copied to @buffer.
545 */
546 size_t get_entity_version(char *buffer, size_t bufsz);
547
548 /**
549 * kv_strip - Strip blanks from key value string
550 * @kv: The key-value string to strip
551 *
552 * Strip leading/trailing blanks as well as trailing comments from the
553 * Key=Value string pointed to by @kv.
554 *
555 * Return: A pointer to the stripped string. Note that the original string,
556 * @kv, gets modified.
557 */
558 char *kv_strip(char *kv);
559
560 /**
561 * kv_keymatch - Look for key in key value string
562 * @kv: The key=value string to search for the presence of @key
563 * @key: The key to look for
564 *
565 * Look for @key in the Key=Value pair pointed to by @k and return a
566 * pointer to the Value if @key is found.
567 *
568 * Check if @kv starts with @key. If it does then make sure that we
569 * have a whole-word match on the @key, and if we do, return a pointer
570 * to the first character of value (i.e. skip leading spaces, tabs,
571 * and equal sign)
572 *
573 * Return: A pointer to the first character of "value" if a match is found.
574 * NULL otherwise.
575 */
576 char *kv_keymatch(const char *kv, const char *key);
577
578 /**
579 * startswith - Checks that a string starts with a given prefix.
580 * @s: The string to check
581 * @prefix: A string that @s could be starting with
582 *
583 * Return: If @s starts with @prefix, then return a pointer within @s at
584 * the first character after the matched @prefix. NULL otherwise.
585 */
586 char *startswith(const char *s, const char *prefix);
587
588 #define __round_mask(val, mult) ((__typeof__(val))((mult)-1))
589
590 /**
591 * round_up - Round a value @val to the next multiple specified by @mult.
592 * @val: Value to round
593 * @mult: Multiple to round to.
594 *
595 * usage: int x = round_up(13, sizeof(__u32)); // 13 -> 16
596 */
597 #define round_up(val, mult) ((((val)-1) | __round_mask((val), (mult)))+1)
598
599 /**
600 * nvmf_exat_len() - Return length rounded up by 4
601 * @val_len: Value length
602 *
603 * Return the size in bytes, rounded to a multiple of 4 (e.g., size of
604 * __u32), of the buffer needed to hold the exat value of size
605 * @val_len.
606 *
607 * Return: Length rounded up by 4
608 */
609 static inline __u16 nvmf_exat_len(size_t val_len)
610 {
611 return (__u16)round_up(val_len, sizeof(__u32));
612 }
613
614 /**
615 * nvmf_exat_size - Return min aligned size to hold value
616 * @val_len: This is the length of the data to be copied to the "exatval"
617 * field of a "struct nvmf_ext_attr".
618 *
619 * Return the size of the "struct nvmf_ext_attr" needed to hold
620 * a value of size @val_len.
621 *
622 * Return: The size in bytes, rounded to a multiple of 4 (i.e. size of
623 * __u32), of the "struct nvmf_ext_attr" required to hold a string of
624 * length @val_len.
625 */
626 static inline __u16 nvmf_exat_size(size_t val_len)
627 {
628 return (__u16)(sizeof(struct nvmf_ext_attr) + nvmf_exat_len(val_len));
629 }
630
631 /**
632 * nvmf_exat_ptr_next - Increment @p to the next element in the array.
633 * @p: Pointer to an element of an array of "struct nvmf_ext_attr".
634 *
635 * Extended attributes are saved to an array of "struct nvmf_ext_attr"
636 * where each element of the array is of variable size. In order to
637 * move to the next element in the array one must increment the
638 * pointer to the current element (@p) by the size of the current
639 * element.
640 *
641 * Return: Pointer to the next element in the array.
642 */
643 struct nvmf_ext_attr *nvmf_exat_ptr_next(struct nvmf_ext_attr *p);
644
645 /**
646 * enum nvme_version - Selector for version to be returned by @nvme_get_version
647 *
648 * @NVME_VERSION_PROJECT: Project release version
649 * @NVME_VERSION_GIT: Git reference
650 */
651 enum nvme_version {
652 NVME_VERSION_PROJECT = 0,
653 NVME_VERSION_GIT = 1,
654 };
655
656 /**
657 * nvme_get_version - Return version libnvme string
658 * @type: Selects which version type (see @struct nvme_version)
659 *
660 * Return: Returns version string for known types or else "n/a"
661 */
662 const char *nvme_get_version(enum nvme_version type);
663
664 /**
665 * nvme_uuid_to_string - Return string represenation of encoded UUID
666 * @uuid: Binary encoded input UUID
667 * @str: Output string represenation of UUID
668 *
669 * Return: Returns error code if type conversion fails.
670 */
671 int nvme_uuid_to_string(unsigned char uuid[NVME_UUID_LEN], char *str);
672
673 /**
674 * nvme_uuid_from_string - Return encoded UUID represenation of string UUID
675 * @uuid: Binary encoded input UUID
676 * @str: Output string represenation of UUID
677 *
678 * Return: Returns error code if type conversion fails.
679 */
680 int nvme_uuid_from_string(const char *str, unsigned char uuid[NVME_UUID_LEN]);
681
682 /**
683 * nvme_uuid_random - Generate random UUID
684 * @uuid: Generated random UUID
685 *
686 * Generate random number according
687 * https://www.rfc-editor.org/rfc/rfc4122#section-4.4
688 *
689 * Return: Returns error code if generating of random number fails.
690 */
691 int nvme_uuid_random(unsigned char uuid[NVME_UUID_LEN]);
692
693 /**
694 * nvme_uuid_find - Find UUID position on UUID list
695 * @uuid_list: UUID list returned by identify UUID
696 * @uuid: Binary encoded input UUID
697 *
698 * Return: The array position where given UUID is present, or -1 on failure with errno set.
699 */
700 int nvme_uuid_find(struct nvme_id_uuid_list *uuid_list, const unsigned char uuid[NVME_UUID_LEN]);
701
702 /**
703 * nvme_ipaddrs_eq - Check if 2 IP addresses are equal.
704 * @addr1: IP address (can be IPv4 or IPv6)
705 * @addr2: IP address (can be IPv4 or IPv6)
706 *
707 * Return: true if addr1 == addr2. false otherwise.
708 */
709 bool nvme_ipaddrs_eq(const char *addr1, const char *addr2);
710
711 /**
712 * nvme_iface_matching_addr - Get interface matching @addr
713 * @iface_list: Interface list returned by getifaddrs()
714 * @addr: Address to match
715 *
716 * Parse the interface list pointed to by @iface_list looking
717 * for the interface that has @addr as one of its assigned
718 * addresses.
719 *
720 * Return: The name of the interface that owns @addr or NULL.
721 */
722 const char *nvme_iface_matching_addr(const struct ifaddrs *iface_list, const char *addr);
723
724 /**
725 * nvme_iface_primary_addr_matches - Check that interface's primary address matches
726 * @iface_list: Interface list returned by getifaddrs()
727 * @iface: Interface to match
728 * @addr: Address to match
729 *
730 * Parse the interface list pointed to by @iface_list and looking for
731 * interface @iface. The get its primary address and check if it matches
732 * @addr.
733 *
734 * Return: true if a match is found, false otherwise.
735 */
736 bool nvme_iface_primary_addr_matches(const struct ifaddrs *iface_list, const char *iface, const char *addr);
737
738 #endif /* _LIBNVME_UTIL_H */