Debian Codegraph @

src/nvme/tree.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
10 #ifndef _LIBNVME_TREE_H
11 #define _LIBNVME_TREE_H
12
13 #include <stdio.h>
14 #include <stdbool.h>
15 #include <stddef.h>
16
17 #include <sys/types.h>
18 #include <netinet/in.h>
19
20 #include <nvme/ioctl.h>
21 #include <nvme/util.h>
22
23 /**
24 * DOC: tree.h
25 *
26 * libnvme tree object interface
27 */
28
29 typedef struct nvme_ns *nvme_ns_t;
30 typedef struct nvme_ns_head *nvme_ns_head_t;
31 typedef struct nvme_path *nvme_path_t;
32 typedef struct nvme_ctrl *nvme_ctrl_t;
33 typedef struct nvme_subsystem *nvme_subsystem_t;
34 typedef struct nvme_host *nvme_host_t;
35 typedef struct nvme_root *nvme_root_t;
36
37 typedef bool (*nvme_scan_filter_t)(nvme_subsystem_t, nvme_ctrl_t,
38 nvme_ns_t, void *);
39
40 /**
41 * nvme_create_root() - Initialize root object
42 * @fp: File descriptor for logging messages
43 * @log_level: Logging level to use
44 *
45 * Return: Initialized &nvme_root_t object
46 */
47 nvme_root_t nvme_create_root(FILE *fp, int log_level);
48
49 /**
50 * nvme_root_set_application - Specify managing application
51 * @r: &nvme_root_t object
52 * @a: Application string
53 *
54 * Sets the managing application string for @r.
55 */
56 void nvme_root_set_application(nvme_root_t r, const char *a);
57
58 /**
59 * nvme_root_get_application - Get managing application
60 * @r: &nvme_root_t object
61 *
62 * Returns the managing application string for @r or NULL if not set.
63 */
64 const char *nvme_root_get_application(nvme_root_t r);
65
66 /**
67 * nvme_root_skip_namespaces - Skip namespace scanning
68 * @r: &nvme_root_t object
69 *
70 * Sets a flag to skip namespaces during scanning.
71 */
72 void nvme_root_skip_namespaces(nvme_root_t r);
73
74 /**
75 * nvme_root_release_fds - Close all opened file descriptors in the tree
76 * @r: &nvme_root_t object
77 *
78 * Controller and Namespace objects cache the file descriptors
79 * of opened nvme devices. This API can be used to close and
80 * clear all cached fds in the tree.
81 *
82 */
83 void nvme_root_release_fds(nvme_root_t r);
84
85 /**
86 * nvme_free_tree() - Free root object
87 * @r: &nvme_root_t object
88 *
89 * Free an &nvme_root_t object and all attached objects
90 */
91 void nvme_free_tree(nvme_root_t r);
92
93 /**
94 * nvme_first_host() - Start host iterator
95 * @r: &nvme_root_t object
96 *
97 * Return: First &nvme_host_t object in an iterator
98 */
99 nvme_host_t nvme_first_host(nvme_root_t r);
100
101 /**
102 * nvme_next_host() - Next host iterator
103 * @r: &nvme_root_t object
104 * @h: Previous &nvme_host_t iterator
105 *
106 * Return: Next &nvme_host_t object in an iterator
107 */
108 nvme_host_t nvme_next_host(nvme_root_t r, nvme_host_t h);
109
110 /**
111 * nvme_host_get_root() - Returns nvme_root_t object
112 * @h: &nvme_host_t object
113 *
114 * Return: &nvme_root_t object from @h
115 */
116 nvme_root_t nvme_host_get_root(nvme_host_t h);
117
118 /**
119 * nvme_lookup_host() - Lookup nvme_host_t object
120 * @r: &nvme_root_t object
121 * @hostnqn: Host NQN
122 * @hostid: Host ID
123 *
124 * Lookup a nvme_host_t object based on @hostnqn and @hostid
125 * or create one if not found.
126 *
127 * Return: &nvme_host_t object
128 */
129 nvme_host_t nvme_lookup_host(nvme_root_t r, const char *hostnqn,
130 const char *hostid);
131
132 /**
133 * nvme_host_get_dhchap_key() - Return host key
134 * @h: Host for which the key should be returned
135 *
136 * Return: DH-HMAC-CHAP host key or NULL if not set
137 */
138 const char *nvme_host_get_dhchap_key(nvme_host_t h);
139
140 /**
141 * nvme_host_set_dhchap_key() - set host key
142 * @h: Host for which the key should be set
143 * @key: DH-HMAC-CHAP Key to set or NULL to clear existing key
144 */
145 void nvme_host_set_dhchap_key(nvme_host_t h, const char *key);
146
147 /**
148 * nvme_host_set_pdc_enabled() - Set Persistent Discovery Controller flag
149 * @h: Host for which the falg should be set
150 * @enabled: The bool to set the enabled flag
151 *
152 * When nvme_host_set_pdc_enabled() is not used to set the PDC flag,
153 * nvme_host_is_pdc_enabled() will return the default value which was
154 * passed into the function and not the undefined flag value.
155 */
156 void nvme_host_set_pdc_enabled(nvme_host_t h, bool enabled);
157
158 /**
159 * nvme_host_is_pdc_enabled() - Is Persistenct Discovery Controller enabled
160 * @h: Host which to check if PDC is enabled
161 * @fallback: The fallback default value of the flag when
162 * @nvme_host_set_pdc_enabled has not be used
163 * to set the flag.
164 *
165 * Return: true if PDC is enabled for @h, else false
166 */
167 bool nvme_host_is_pdc_enabled(nvme_host_t h, bool fallback);
168
169 /**
170 * nvme_default_host() - Initializes the default host
171 * @r: &nvme_root_t object
172 *
173 * Initializes the default host object based on the hostnqn/hostid
174 * values returned by nvme_host_get_ids() and attaches it to @r.
175 *
176 * Return: &nvme_host_t object
177 */
178 nvme_host_t nvme_default_host(nvme_root_t r);
179
180 /**
181 * nvme_host_get_ids - Retrieve host ids from various sources
182 *
183 * @r: &nvme_root_t object
184 * @hostnqn_arg: Input hostnqn (command line) argument
185 * @hostid_arg: Input hostid (command line) argument
186 * @hostnqn: Output hostnqn
187 * @hostid: Output hostid
188 *
189 * nvme_host_get_ids figures out which hostnqn/hostid is to be used.
190 * There are several sources where this information can be retrieved.
191 *
192 * The order is:
193 *
194 * - Start with informartion from DMI or device-tree
195 * - Override hostnqn and hostid from /etc/nvme files
196 * - Override hostnqn or hostid with values from JSON
197 * configuration file. The first host entry in the file is
198 * considered the default host.
199 * - Override hostnqn or hostid with values from the command line
200 * (@hostnqn_arg, @hostid_arg).
201 *
202 * If the IDs are still NULL after the lookup algorithm, the function
203 * will generate random IDs.
204 *
205 * The function also verifies that hostnqn and hostid matches. The Linux
206 * NVMe implementation expects a 1:1 matching between the IDs.
207 *
208 * Return: 0 on success (@hostnqn and @hostid contain valid strings
209 * which the caller needs to free), -1 otherwise and errno is set.
210 */
211 int nvme_host_get_ids(nvme_root_t r,
212 char *hostnqn_arg, char *hostid_arg,
213 char **hostnqn, char **hostid);
214
215 /**
216 * nvme_first_subsystem() - Start subsystem iterator
217 * @h: &nvme_host_t object
218 *
219 * Return: first &nvme_subsystem_t object in an iterator
220 */
221 nvme_subsystem_t nvme_first_subsystem(nvme_host_t h);
222
223 /**
224 * nvme_next_subsystem() - Next subsystem iterator
225 * @h: &nvme_host_t object
226 * @s: Previous &nvme_subsystem_t iterator
227 *
228 * Return: next &nvme_subsystem_t object in an iterator
229 */
230 nvme_subsystem_t nvme_next_subsystem(nvme_host_t h, nvme_subsystem_t s);
231
232 /**
233 * nvme_lookup_subsystem() - Lookup nvme_subsystem_t object
234 * @h: &nvme_host_t object
235 * @name: Name of the subsystem (may be NULL)
236 * @subsysnqn: Subsystem NQN
237 *
238 * Lookup a &nvme_subsystem_t object in @h base on @name (if present)
239 * and @subsysnqn or create one if not found.
240 *
241 * Return: nvme_subsystem_t object
242 */
243 nvme_subsystem_t nvme_lookup_subsystem(struct nvme_host *h,
244 const char *name,
245 const char *subsysnqn);
246
247 /**
248 * nvme_free_subsystem() - Free a subsystem
249 * @s: subsystem
250 *
251 * Frees @s and all related objects.
252 */
253 void nvme_free_subsystem(struct nvme_subsystem *s);
254
255 /**
256 * nvme_subsystem_get_host() - Returns nvme_host_t object
257 * @s: subsystem
258 *
259 * Return: &nvme_host_t object from @s
260 */
261 nvme_host_t nvme_subsystem_get_host(nvme_subsystem_t s);
262
263 /**
264 * nvme_ctrl_first_ns() - Start namespace iterator
265 * @c: Controller instance
266 *
267 * Return: First &nvme_ns_t object of an @c iterator
268 */
269 nvme_ns_t nvme_ctrl_first_ns(nvme_ctrl_t c);
270
271 /**
272 * nvme_ctrl_next_ns() - Next namespace iterator
273 * @c: Controller instance
274 * @n: Previous nvme_ns_t iterator
275 *
276 * Return: Next nvme_ns_t object of an @c iterator
277 */
278 nvme_ns_t nvme_ctrl_next_ns(nvme_ctrl_t c, nvme_ns_t n);
279
280 /**
281 * nvme_ctrl_first_path() - Start path iterator
282 * @c: Controller instance
283 *
284 * Return: First &nvme_path_t object of an @c iterator
285 */
286 nvme_path_t nvme_ctrl_first_path(nvme_ctrl_t c);
287
288 /**
289 * nvme_ctrl_next_path() - Next path iterator
290 * @c: Controller instance
291 * @p: Previous &nvme_path_t object of an @c iterator
292 *
293 * Return: Next &nvme_path_t object of an @c iterator
294 */
295 nvme_path_t nvme_ctrl_next_path(nvme_ctrl_t c, nvme_path_t p);
296
297 /**
298 * nvme_subsystem_first_ctrl() - First ctrl iterator
299 * @s: &nvme_subsystem_t object
300 *
301 * Return: First controller of an @s iterator
302 */
303 nvme_ctrl_t nvme_subsystem_first_ctrl(nvme_subsystem_t s);
304
305 /**
306 * nvme_subsystem_next_ctrl() - Next ctrl iterator
307 * @s: &nvme_subsystem_t object
308 * @c: Previous controller instance of an @s iterator
309 *
310 * Return: Next controller of an @s iterator
311 */
312 nvme_ctrl_t nvme_subsystem_next_ctrl(nvme_subsystem_t s, nvme_ctrl_t c);
313
314 /**
315 * nvme_namespace_first_path() - Start path iterator
316 * @ns: Namespace instance
317 *
318 * Return: First &nvme_path_t object of an @ns iterator
319 */
320 nvme_path_t nvme_namespace_first_path(nvme_ns_t ns);
321
322 /**
323 * nvme_namespace_next_path() - Next path iterator
324 * @ns: Namespace instance
325 * @p: Previous &nvme_path_t object of an @ns iterator
326 *
327 * Return: Next &nvme_path_t object of an @ns iterator
328 */
329 nvme_path_t nvme_namespace_next_path(nvme_ns_t ns, nvme_path_t p);
330
331 /**
332 * nvme_lookup_ctrl() - Lookup nvme_ctrl_t object
333 * @s: &nvme_subsystem_t object
334 * @transport: Transport name
335 * @traddr: Transport address
336 * @host_traddr: Host transport address
337 * @host_iface: Host interface name
338 * @trsvcid: Transport service identifier
339 * @p: Previous controller instance
340 *
341 * Lookup a controller in @s based on @transport, @traddr,
342 * @host_traddr, @host_iface, and @trsvcid. @transport must be specified,
343 * other fields may be required depending on the transport. A new
344 * object is created if none is found. If @p is specified the lookup
345 * will start at @p instead of the first controller.
346 *
347 * Return: Controller instance
348 */
349 nvme_ctrl_t nvme_lookup_ctrl(nvme_subsystem_t s, const char *transport,
350 const char *traddr, const char *host_traddr,
351 const char *host_iface, const char *trsvcid,
352 nvme_ctrl_t p);
353
354 /**
355 * nvme_ctrl_find() - Locate an existing controller
356 * @s: &nvme_subsystem_t object
357 * @transport: Transport name
358 * @traddr: Transport address
359 * @trsvcid: Transport service identifier
360 * @subsysnqn: Subsystem NQN
361 * @host_traddr: Host transport address
362 * @host_iface: Host interface name
363 *
364 * Lookup a controller in @s based on @transport, @traddr, @trsvcid,
365 * @subsysnqn, @host_traddr, and @host_iface. @transport must be specified,
366 * other fields may be required depending on the transport. Parameters set
367 * to NULL will be ignored.
368 *
369 * Unlike nvme_lookup_ctrl(), this function does not create a new object if
370 * an existing controller cannot be found.
371 *
372 * Return: Controller instance on success, NULL otherwise.
373 */
374 nvme_ctrl_t nvme_ctrl_find(nvme_subsystem_t s, const char *transport,
375 const char *traddr, const char *trsvcid,
376 const char *subsysnqn, const char *host_traddr,
377 const char *host_iface);
378
379 /**
380 * nvme_ctrl_config_match() - Check if ctrl @c matches config params
381 * @c: An existing controller instance
382 * @transport: Transport name
383 * @traddr: Transport address
384 * @trsvcid: Transport service identifier
385 * @subsysnqn: Subsystem NQN
386 * @host_traddr: Host transport address
387 * @host_iface: Host interface name
388 *
389 * Check that controller @c matches parameters: @transport, @traddr,
390 * @trsvcid, @subsysnqn, @host_traddr, and @host_iface. Parameters set
391 * to NULL will be ignored.
392 *
393 * Return: true if there's a match, false otherwise.
394 */
395 bool nvme_ctrl_config_match(struct nvme_ctrl *c, const char *transport,
396 const char *traddr, const char *trsvcid,
397 const char *subsysnqn, const char *host_traddr,
398 const char *host_iface);
399
400 /**
401 * nvme_create_ctrl() - Allocate an unconnected NVMe controller
402 * @r: NVMe root element
403 * @subsysnqn: Subsystem NQN
404 * @transport: Transport type
405 * @traddr: Transport address
406 * @host_traddr: Host transport address
407 * @host_iface: Host interface name
408 * @trsvcid: Transport service ID
409 *
410 * Creates an unconnected controller to be used for nvme_add_ctrl().
411 *
412 * Return: Controller instance
413 */
414 nvme_ctrl_t nvme_create_ctrl(nvme_root_t r,
415 const char *subsysnqn, const char *transport,
416 const char *traddr, const char *host_traddr,
417 const char *host_iface, const char *trsvcid);
418
419
420 /**
421 * nvme_subsystem_first_ns() - Start namespace iterator
422 * @s: &nvme_subsystem_t object
423 *
424 * Return: First &nvme_ns_t object of an @s iterator
425 */
426 nvme_ns_t nvme_subsystem_first_ns(nvme_subsystem_t s);
427
428 /**
429 * nvme_subsystem_next_ns() - Next namespace iterator
430 * @s: &nvme_subsystem_t object
431 * @n: Previous &nvme_ns_t iterator
432 *
433 * Return: Next &nvme_ns_t object of an @s iterator
434 */
435 nvme_ns_t nvme_subsystem_next_ns(nvme_subsystem_t s, nvme_ns_t n);
436
437 /**
438 * nvme_for_each_host_safe() - Traverse host list
439 * @r: &nvme_root_t object
440 * @h: &nvme_host_t object
441 * @_h: Temporary &nvme_host_t object
442 */
443 #define nvme_for_each_host_safe(r, h, _h) \
444 for (h = nvme_first_host(r), \
445 _h = nvme_next_host(r, h); \
446 h != NULL; \
447 h = _h, _h = nvme_next_host(r, h))
448
449 /**
450 * nvme_for_each_host() - Traverse host list
451 * @r: &nvme_root_t object
452 * @h: &nvme_host_t object
453 */
454 #define nvme_for_each_host(r, h) \
455 for (h = nvme_first_host(r); h != NULL; \
456 h = nvme_next_host(r, h))
457
458 /**
459 * nvme_for_each_subsystem_safe() - Traverse subsystems
460 * @h: &nvme_host_t object
461 * @s: &nvme_subsystem_t object
462 * @_s: Temporary &nvme_subsystem_t object
463 */
464 #define nvme_for_each_subsystem_safe(h, s, _s) \
465 for (s = nvme_first_subsystem(h), \
466 _s = nvme_next_subsystem(h, s); \
467 s != NULL; \
468 s = _s, _s = nvme_next_subsystem(h, s))
469
470 /**
471 * nvme_for_each_subsystem() - Traverse subsystems
472 * @h: &nvme_host_t object
473 * @s: &nvme_subsystem_t object
474 */
475 #define nvme_for_each_subsystem(h, s) \
476 for (s = nvme_first_subsystem(h); s != NULL; \
477 s = nvme_next_subsystem(h, s))
478
479 /**
480 * nvme_subsystem_for_each_ctrl_safe() - Traverse controllers
481 * @s: &nvme_subsystem_t object
482 * @c: Controller instance
483 * @_c: A &nvme_ctrl_t_node to use as temporary storage
484 */
485 #define nvme_subsystem_for_each_ctrl_safe(s, c, _c) \
486 for (c = nvme_subsystem_first_ctrl(s), \
487 _c = nvme_subsystem_next_ctrl(s, c); \
488 c != NULL; \
489 c = _c, _c = nvme_subsystem_next_ctrl(s, c))
490
491 /**
492 * nvme_subsystem_for_each_ctrl() - Traverse controllers
493 * @s: &nvme_subsystem_t object
494 * @c: Controller instance
495 */
496 #define nvme_subsystem_for_each_ctrl(s, c) \
497 for (c = nvme_subsystem_first_ctrl(s); c != NULL; \
498 c = nvme_subsystem_next_ctrl(s, c))
499
500 /**
501 * nvme_ctrl_for_each_ns_safe() - Traverse namespaces
502 * @c: Controller instance
503 * @n: &nvme_ns_t object
504 * @_n: A &nvme_ns_t_node to use as temporary storage
505 */
506 #define nvme_ctrl_for_each_ns_safe(c, n, _n) \
507 for (n = nvme_ctrl_first_ns(c), \
508 _n = nvme_ctrl_next_ns(c, n); \
509 n != NULL; \
510 n = _n, _n = nvme_ctrl_next_ns(c, n))
511
512 /**
513 * nvme_ctrl_for_each_ns() - Traverse namespaces
514 * @c: Controller instance
515 * @n: &nvme_ns_t object
516 */
517 #define nvme_ctrl_for_each_ns(c, n) \
518 for (n = nvme_ctrl_first_ns(c); n != NULL; \
519 n = nvme_ctrl_next_ns(c, n))
520
521 /**
522 * nvme_ctrl_for_each_path_safe() - Traverse paths
523 * @c: Controller instance
524 * @p: &nvme_path_t object
525 * @_p: A &nvme_path_t_node to use as temporary storage
526 */
527 #define nvme_ctrl_for_each_path_safe(c, p, _p) \
528 for (p = nvme_ctrl_first_path(c), \
529 _p = nvme_ctrl_next_path(c, p); \
530 p != NULL; \
531 p = _p, _p = nvme_ctrl_next_path(c, p))
532
533 /**
534 * nvme_ctrl_for_each_path() - Traverse paths
535 * @c: Controller instance
536 * @p: &nvme_path_t object
537 */
538 #define nvme_ctrl_for_each_path(c, p) \
539 for (p = nvme_ctrl_first_path(c); p != NULL; \
540 p = nvme_ctrl_next_path(c, p))
541
542 /**
543 * nvme_subsystem_for_each_ns_safe() - Traverse namespaces
544 * @s: &nvme_subsystem_t object
545 * @n: &nvme_ns_t object
546 * @_n: A &nvme_ns_t_node to use as temporary storage
547 */
548 #define nvme_subsystem_for_each_ns_safe(s, n, _n) \
549 for (n = nvme_subsystem_first_ns(s), \
550 _n = nvme_subsystem_next_ns(s, n); \
551 n != NULL; \
552 n = _n, _n = nvme_subsystem_next_ns(s, n))
553
554 /**
555 * nvme_subsystem_for_each_ns() - Traverse namespaces
556 * @s: &nvme_subsystem_t object
557 * @n: &nvme_ns_t object
558 */
559 #define nvme_subsystem_for_each_ns(s, n) \
560 for (n = nvme_subsystem_first_ns(s); n != NULL; \
561 n = nvme_subsystem_next_ns(s, n))
562
563 /**
564 * nvme_namespace_for_each_path_safe() - Traverse paths
565 * @n: Namespace instance
566 * @p: &nvme_path_t object
567 * @_p: A &nvme_path_t_node to use as temporary storage
568 */
569 #define nvme_namespace_for_each_path_safe(n, p, _p) \
570 for (p = nvme_namespace_first_path(n), \
571 _p = nvme_namespace_next_path(n, p); \
572 p != NULL; \
573 p = _p, _p = nvme_namespace_next_path(n, p))
574
575 /**
576 * nvme_namespace_for_each_path() - Traverse paths
577 * @n: Namespace instance
578 * @p: &nvme_path_t object
579 */
580 #define nvme_namespace_for_each_path(n, p) \
581 for (p = nvme_namespace_first_path(n); p != NULL; \
582 p = nvme_namespace_next_path(n, p))
583
584 /**
585 * nvme_ns_get_fd() - Get associated file descriptor
586 * @n: Namespace instance
587 *
588 * libnvme will open() the file (if not already opened) and keep
589 * an internal copy of the file descriptor. Following calls to
590 * this API retrieve the internal cached copy of the file
591 * descriptor. The file will remain opened and the fd will
592 * remain cached until the ns object is deleted or
593 * nvme_ns_release_fd() is called.
594 *
595 * Return: File descriptor associated with @n or -1
596 */
597 int nvme_ns_get_fd(nvme_ns_t n);
598
599 /**
600 * nvme_ns_release_fd() - Close fd and clear fd from ns object
601 * @n: Namespace instance
602 *
603 */
604 void nvme_ns_release_fd(nvme_ns_t n);
605
606 /**
607 * nvme_ns_get_nsid() - NSID of a namespace
608 * @n: Namespace instance
609 *
610 * Return: NSID of @n
611 */
612 int nvme_ns_get_nsid(nvme_ns_t n);
613
614 /**
615 * nvme_ns_get_lba_size() - LBA size of a namespace
616 * @n: Namespace instance
617 *
618 * Return: LBA size of @n
619 */
620 int nvme_ns_get_lba_size(nvme_ns_t n);
621
622 /**
623 * nvme_ns_get_meta_size() - Metadata size of a namespace
624 * @n: Namespace instance
625 *
626 * Return: Metadata size of @n
627 */
628 int nvme_ns_get_meta_size(nvme_ns_t n);
629
630 /**
631 * nvme_ns_get_lba_count() - LBA count of a namespace
632 * @n: Namespace instance
633 *
634 * Return: LBA count of @n
635 */
636 uint64_t nvme_ns_get_lba_count(nvme_ns_t n);
637
638 /**
639 * nvme_ns_get_lba_util() - LBA utilization of a namespace
640 * @n: Namespace instance
641 *
642 * Return: LBA utilization of @n
643 */
644 uint64_t nvme_ns_get_lba_util(nvme_ns_t n);
645
646 /**
647 * nvme_ns_get_csi() - Command set identifier of a namespace
648 * @n: Namespace instance
649 *
650 * Return: The namespace's command set identifier in use
651 */
652 enum nvme_csi nvme_ns_get_csi(nvme_ns_t n);
653
654 /**
655 * nvme_ns_get_eui64() - 64-bit eui of a namespace
656 * @n: Namespace instance
657 *
658 * Return: A pointer to the 64-bit eui
659 */
660 const uint8_t *nvme_ns_get_eui64(nvme_ns_t n);
661
662 /**
663 * nvme_ns_get_nguid() - 128-bit nguid of a namespace
664 * @n: Namespace instance
665 *
666 * Return: A pointer to the 128-bit nguid
667 */
668 const uint8_t *nvme_ns_get_nguid(nvme_ns_t n);
669
670 /**
671 * nvme_ns_get_uuid() - UUID of a namespace
672 * @n: Namespace instance
673 * @out: buffer for the UUID
674 *
675 * Copies the namespace's uuid into @out
676 */
677 void nvme_ns_get_uuid(nvme_ns_t n, unsigned char out[NVME_UUID_LEN]);
678
679 /**
680 * nvme_ns_get_sysfs_dir() - sysfs directory of a namespace
681 * @n: Namespace instance
682 *
683 * Return: sysfs directory name of @n
684 */
685 const char *nvme_ns_get_sysfs_dir(nvme_ns_t n);
686
687 /**
688 * nvme_ns_get_name() - sysfs name of a namespace
689 * @n: Namespace instance
690 *
691 * Return: sysfs name of @n
692 */
693 const char *nvme_ns_get_name(nvme_ns_t n);
694
695 /**
696 * nvme_ns_get_generic_name() - Returns name of generic namespace chardev.
697 * @n: Namespace instance
698 *
699 * Return: Name of generic namespace chardev
700 */
701 const char *nvme_ns_get_generic_name(nvme_ns_t n);
702
703 /**
704 * nvme_ns_get_firmware() - Firmware string of a namespace
705 * @n: Namespace instance
706 *
707 * Return: Firmware string of @n
708 */
709 const char *nvme_ns_get_firmware(nvme_ns_t n);
710
711 /**
712 * nvme_ns_get_serial() - Serial number of a namespace
713 * @n: Namespace instance
714 *
715 * Return: Serial number string of @n
716 */
717 const char *nvme_ns_get_serial(nvme_ns_t n);
718
719 /**
720 * nvme_ns_get_model() - Model of a namespace
721 * @n: Namespace instance
722 *
723 * Return: Model string of @n
724 */
725 const char *nvme_ns_get_model(nvme_ns_t n);
726
727 /**
728 * nvme_ns_get_subsystem() - &nvme_subsystem_t of a namespace
729 * @n: Namespace instance
730 *
731 * Return: nvme_subsystem_t object of @n
732 */
733 nvme_subsystem_t nvme_ns_get_subsystem(nvme_ns_t n);
734
735 /**
736 * nvme_ns_get_ctrl() - &nvme_ctrl_t of a namespace
737 * @n: Namespace instance
738 *
739 * nvme_ctrl_t object may be NULL for a multipathed namespace
740 *
741 * Return: nvme_ctrl_t object of @n if present
742 */
743 nvme_ctrl_t nvme_ns_get_ctrl(nvme_ns_t n);
744
745 /**
746 * nvme_free_ns() - Free a namespace object
747 * @n: Namespace instance
748 */
749 void nvme_free_ns(struct nvme_ns *n);
750
751 /**
752 * nvme_ns_read() - Read from a namespace
753 * @n: Namespace instance
754 * @buf: Buffer into which the data will be transferred
755 * @offset: LBA offset of @n
756 * @count: Number of sectors in @buf
757 *
758 * Return: Number of sectors read or -1 on error.
759 */
760 int nvme_ns_read(nvme_ns_t n, void *buf, off_t offset, size_t count);
761
762 /**
763 * nvme_ns_write() - Write to a namespace
764 * @n: Namespace instance
765 * @buf: Buffer with data to be written
766 * @offset: LBA offset of @n
767 * @count: Number of sectors in @buf
768 *
769 * Return: Number of sectors written or -1 on error
770 */
771 int nvme_ns_write(nvme_ns_t n, void *buf, off_t offset, size_t count);
772
773 /**
774 * nvme_ns_verify() - Verify data on a namespace
775 * @n: Namespace instance
776 * @offset: LBA offset of @n
777 * @count: Number of sectors to be verified
778 *
779 * Return: Number of sectors verified
780 */
781 int nvme_ns_verify(nvme_ns_t n, off_t offset, size_t count);
782
783 /**
784 * nvme_ns_compare() - Compare data on a namespace
785 * @n: Namespace instance
786 * @buf: Buffer with data to be compared
787 * @offset: LBA offset of @n
788 * @count: Number of sectors in @buf
789 *
790 * Return: Number of sectors compared
791 */
792 int nvme_ns_compare(nvme_ns_t n, void *buf, off_t offset, size_t count);
793
794 /**
795 * nvme_ns_write_zeros() - Write zeros to a namespace
796 * @n: Namespace instance
797 * @offset: LBA offset in @n
798 * @count: Number of sectors to be written
799 *
800 * Return: Number of sectors written
801 */
802 int nvme_ns_write_zeros(nvme_ns_t n, off_t offset, size_t count);
803
804 /**
805 * nvme_ns_write_uncorrectable() - Issus a 'write uncorrectable' command
806 * @n: Namespace instance
807 * @offset: LBA offset in @n
808 * @count: Number of sectors to be written
809 *
810 * Return: Number of sectors written
811 */
812 int nvme_ns_write_uncorrectable(nvme_ns_t n, off_t offset, size_t count);
813
814 /**
815 * nvme_ns_flush() - Flush data to a namespace
816 * @n: Namespace instance
817 *
818 * Return: 0 on success, -1 on error.
819 */
820 int nvme_ns_flush(nvme_ns_t n);
821
822 /**
823 * nvme_ns_identify() - Issue an 'identify namespace' command
824 * @n: Namespace instance
825 * @ns: &nvme_id_ns buffer
826 *
827 * Writes the data returned by the 'identify namespace' command
828 * into @ns.
829 *
830 * Return: 0 on success, -1 on error.
831 */
832 int nvme_ns_identify(nvme_ns_t n, struct nvme_id_ns *ns);
833
834 /**
835 * nvme_ns_identify_descs() - Issue an 'identify descriptors' command
836 * @n: Namespace instance
837 * @descs: List of identify descriptors
838 *
839 * Writes the data returned by the 'identify descriptors' command
840 * into @descs.
841 *
842 * Return: 0 on success, -1 on error.
843 */
844 int nvme_ns_identify_descs(nvme_ns_t n, struct nvme_ns_id_desc *descs);
845
846 /**
847 * nvme_path_get_name() - sysfs name of an &nvme_path_t object
848 * @p: &nvme_path_t object
849 *
850 * Return: sysfs name of @p
851 */
852 const char *nvme_path_get_name(nvme_path_t p);
853
854 /**
855 * nvme_path_get_sysfs_dir() - sysfs directory of an nvme_path_t object
856 * @p: &nvme_path_t object
857 *
858 * Return: sysfs directory of @p
859 */
860 const char *nvme_path_get_sysfs_dir(nvme_path_t p);
861
862 /**
863 * nvme_path_get_ana_state() - ANA state of an nvme_path_t object
864 * @p: &nvme_path_t object
865 *
866 * Return: ANA (Asynchronous Namespace Access) state of @p
867 */
868 const char *nvme_path_get_ana_state(nvme_path_t p);
869
870 /**
871 * nvme_path_get_numa_nodes() - NUMA nodes of an nvme_path_t object
872 * @p : &nvme_path_t object
873 *
874 * Return: NUMA nodes associated to @p
875 */
876 const char *nvme_path_get_numa_nodes(nvme_path_t p);
877
878 /**
879 * nvme_path_get_queue_depth() - Queue depth of an nvme_path_t object
880 * @p: &nvme_path_t object
881 *
882 * Return: Queue depth of @p
883 */
884 int nvme_path_get_queue_depth(nvme_path_t p);
885
886 /**
887 * nvme_path_get_ctrl() - Parent controller of an nvme_path_t object
888 * @p: &nvme_path_t object
889 *
890 * Return: Parent controller if present
891 */
892 nvme_ctrl_t nvme_path_get_ctrl(nvme_path_t p);
893
894 /**
895 * nvme_path_get_ns() - Parent namespace of an nvme_path_t object
896 * @p: &nvme_path_t object
897 *
898 * Return: Parent namespace if present
899 */
900 nvme_ns_t nvme_path_get_ns(nvme_path_t p);
901
902 /**
903 * nvme_ctrl_get_fd() - Get associated file descriptor
904 * @c: Controller instance
905 *
906 * libnvme will open() the file (if not already opened) and keep
907 * an internal copy of the file descriptor. Following calls to
908 * this API retrieve the internal cached copy of the file
909 * descriptor. The file will remain opened and the fd will
910 * remain cached until the controller object is deleted or
911 * nvme_ctrl_release_fd() is called.
912 *
913 * Return: File descriptor associated with @c or -1
914 */
915 int nvme_ctrl_get_fd(nvme_ctrl_t c);
916
917 /**
918 * nvme_ctrl_release_fd() - Close fd and clear fd from controller object
919 * @c: Controller instance
920 *
921 */
922 void nvme_ctrl_release_fd(nvme_ctrl_t c);
923
924 /**
925 * nvme_ctrl_get_name() - sysfs name of a controller
926 * @c: Controller instance
927 *
928 * Return: sysfs name of @c
929 */
930 const char *nvme_ctrl_get_name(nvme_ctrl_t c);
931
932 /**
933 * nvme_ctrl_get_sysfs_dir() - sysfs directory of a controller
934 * @c: Controller instance
935 *
936 * Return: sysfs directory name of @c
937 */
938 const char *nvme_ctrl_get_sysfs_dir(nvme_ctrl_t c);
939
940 /**
941 * nvme_ctrl_get_address() - Address string of a controller
942 * @c: Controller instance
943 *
944 * Return: NVMe-over-Fabrics address string of @c or empty string
945 * of no address is present.
946 */
947 const char *nvme_ctrl_get_address(nvme_ctrl_t c);
948
949 /**
950 * nvme_ctrl_get_src_addr() - Extract src_addr from the c->address string
951 * @c: Controller instance
952 * @src_addr: Where to copy the src_addr. Size must be at least INET6_ADDRSTRLEN.
953 * @src_addr_len: Length of the buffer @src_addr.
954 *
955 * Return: Pointer to @src_addr on success. NULL on failure to extract the src_addr.
956 */
957 char *nvme_ctrl_get_src_addr(nvme_ctrl_t c, char *src_addr, size_t src_addr_len);
958
959 /**
960 * nvme_ctrl_get_phy_slot() - PCI physical slot number of a controller
961 * @c: Controller instance
962 *
963 * Return: PCI physical slot number of @c or empty string if slot
964 * number is not present.
965 */
966 const char *nvme_ctrl_get_phy_slot(nvme_ctrl_t c);
967
968 /**
969 * nvme_ctrl_get_firmware() - Firmware string of a controller
970 * @c: Controller instance
971 *
972 * Return: Firmware string of @c
973 */
974 const char *nvme_ctrl_get_firmware(nvme_ctrl_t c);
975
976 /**
977 * nvme_ctrl_get_model() - Model of a controller
978 * @c: Controller instance
979 *
980 * Return: Model string of @c
981 */
982 const char *nvme_ctrl_get_model(nvme_ctrl_t c);
983
984 /**
985 * nvme_ctrl_get_state() - Running state of a controller
986 * @c: Controller instance
987 *
988 * Return: String indicating the running state of @c
989 */
990 const char *nvme_ctrl_get_state(nvme_ctrl_t c);
991
992 /**
993 * nvme_ctrl_get_numa_node() - NUMA node of a controller
994 * @c: Controller instance
995 *
996 * Return: String indicating the NUMA node
997 */
998 const char *nvme_ctrl_get_numa_node(nvme_ctrl_t c);
999
1000 /**
1001 * nvme_ctrl_get_queue_count() - Queue count of a controller
1002 * @c: Controller instance
1003 *
1004 * Return: Queue count of @c
1005 */
1006 const char *nvme_ctrl_get_queue_count(nvme_ctrl_t c);
1007
1008 /**
1009 * nvme_ctrl_get_serial() - Serial number of a controller
1010 * @c: Controller instance
1011 *
1012 * Return: Serial number string of @c
1013 */
1014 const char *nvme_ctrl_get_serial(nvme_ctrl_t c);
1015
1016 /**
1017 * nvme_ctrl_get_sqsize() - SQ size of a controller
1018 * @c: Controller instance
1019 *
1020 * Return: SQ size (as string) of @c
1021 */
1022 const char *nvme_ctrl_get_sqsize(nvme_ctrl_t c);
1023
1024 /**
1025 * nvme_ctrl_get_transport() - Transport type of a controller
1026 * @c: Controller instance
1027 *
1028 * Return: Transport type of @c
1029 */
1030 const char *nvme_ctrl_get_transport(nvme_ctrl_t c);
1031
1032 /**
1033 * nvme_ctrl_get_subsysnqn() - Subsystem NQN of a controller
1034 * @c: Controller instance
1035 *
1036 * Return: Subsystem NQN of @c
1037 */
1038 const char *nvme_ctrl_get_subsysnqn(nvme_ctrl_t c);
1039
1040 /**
1041 * nvme_ctrl_get_subsystem() - Parent subsystem of a controller
1042 * @c: Controller instance
1043 *
1044 * Return: Parent nvme_subsystem_t object
1045 */
1046 nvme_subsystem_t nvme_ctrl_get_subsystem(nvme_ctrl_t c);
1047
1048 /**
1049 * nvme_ctrl_get_traddr() - Transport address of a controller
1050 * @c: Controller instance
1051 *
1052 * Return: Transport address of @c
1053 */
1054 const char *nvme_ctrl_get_traddr(nvme_ctrl_t c);
1055
1056 /**
1057 * nvme_ctrl_get_trsvcid() - Transport service identifier of a controller
1058 * @c: Controller instance
1059 *
1060 * Return: Transport service identifier of @c (if present)
1061 */
1062 const char *nvme_ctrl_get_trsvcid(nvme_ctrl_t c);
1063
1064 /**
1065 * nvme_ctrl_get_host_traddr() - Host transport address of a controller
1066 * @c: Controller instance
1067 *
1068 * Return: Host transport address of @c (if present)
1069 */
1070 const char *nvme_ctrl_get_host_traddr(nvme_ctrl_t c);
1071
1072 /**
1073 * nvme_ctrl_get_host_iface() - Host interface name of a controller
1074 * @c: Controller instance
1075 *
1076 * Return: Host interface name of @c (if present)
1077 */
1078 const char *nvme_ctrl_get_host_iface(nvme_ctrl_t c);
1079
1080 /**
1081 * nvme_ctrl_get_dhchap_host_key() - Return host key
1082 * @c: Controller to be checked
1083 *
1084 * Return: DH-HMAC-CHAP host key or NULL if not set
1085 */
1086 const char *nvme_ctrl_get_dhchap_host_key(nvme_ctrl_t c);
1087
1088 /**
1089 * nvme_ctrl_get_cntlid() - Controller id
1090 * @c: Controller to be checked
1091 *
1092 * Return : Controller id of @c
1093 */
1094 const char *nvme_ctrl_get_cntlid(nvme_ctrl_t c);
1095
1096 /**
1097 * nvme_ctrl_set_dhchap_host_key() - Set host key
1098 * @c: Host for which the key should be set
1099 * @key: DH-HMAC-CHAP Key to set or NULL to clear existing key
1100 */
1101 void nvme_ctrl_set_dhchap_host_key(nvme_ctrl_t c, const char *key);
1102
1103 /**
1104 * nvme_ctrl_get_dhchap_key() - Return controller key
1105 * @c: Controller for which the key should be set
1106 *
1107 * Return: DH-HMAC-CHAP controller key or NULL if not set
1108 */
1109 const char *nvme_ctrl_get_dhchap_key(nvme_ctrl_t c);
1110
1111 /**
1112 * nvme_ns_head_get_sysfs_dir() - sysfs dir of namespave head
1113 * @head: namespace head instance
1114 *
1115 * Returns: sysfs directory name of @head
1116 */
1117 const char *nvme_ns_head_get_sysfs_dir(nvme_ns_head_t head);
1118
1119 /**
1120 * nvme_ctrl_set_dhchap_key() - Set controller key
1121 * @c: Controller for which the key should be set
1122 * @key: DH-HMAC-CHAP Key to set or NULL to clear existing key
1123 */
1124 void nvme_ctrl_set_dhchap_key(nvme_ctrl_t c, const char *key);
1125
1126 /**
1127 * nvme_ctrl_get_keyring() - Return keyring
1128 * @c: Controller to be used for the lookup
1129 *
1130 * Return: Keyring or NULL if not set
1131 */
1132 const char *nvme_ctrl_get_keyring(nvme_ctrl_t c);
1133
1134 /**
1135 * nvme_ctrl_set_keyring() - Set keyring
1136 * @c: Controller for which the keyring should be set
1137 * @keyring: Keyring name
1138 */
1139 void nvme_ctrl_set_keyring(nvme_ctrl_t c, const char *keyring);
1140
1141 /**
1142 * nvme_ctrl_get_tls_key_identity() - Return Derive TLS Identity
1143 * @c: Controller to be used for the lookup
1144 *
1145 * Return: Derive TLS Identity or NULL if not set
1146 */
1147 const char *nvme_ctrl_get_tls_key_identity(nvme_ctrl_t c);
1148
1149 /**
1150 * nvme_ctrl_set_tls_key_identity() - Set Derive TLS Identity
1151 * @c: Controller for which the key should be set
1152 * @identity: Derive TLS identity or NULL to clear existing key
1153 */
1154 void nvme_ctrl_set_tls_key_identity(nvme_ctrl_t c, const char *identity);
1155
1156 /**
1157 * nvme_ctrl_get_tls_key() - Return Derive TLS PSK
1158 * @c: Controller to be used for the lookup
1159 *
1160 * Return: Key in PSK interchange format or NULL if not set
1161 */
1162 const char *nvme_ctrl_get_tls_key(nvme_ctrl_t c);
1163
1164 /**
1165 * nvme_ctrl_set_tls_key() - Set Derive TLS PSK
1166 * @c: Controller for which the key should be set
1167 * @key: Key in interchange format or NULL to clear existing key
1168 */
1169 void nvme_ctrl_set_tls_key(nvme_ctrl_t c, const char *key);
1170
1171 /**
1172 * nvme_ctrl_get_config() - Fabrics configuration of a controller
1173 * @c: Controller instance
1174 *
1175 * Return: Fabrics configuration of @c
1176 */
1177 struct nvme_fabrics_config *nvme_ctrl_get_config(nvme_ctrl_t c);
1178
1179 /**
1180 * nvme_ctrl_set_discovered() - Set the 'discovered' flag
1181 * @c: nvme_ctrl_t object
1182 * @discovered: Value of the 'discovered' flag
1183 *
1184 * Set the 'discovered' flag of @c to @discovered
1185 */
1186 void nvme_ctrl_set_discovered(nvme_ctrl_t c, bool discovered);
1187
1188 /**
1189 * nvme_ctrl_is_discovered() - Returns the value of the 'discovered' flag
1190 * @c: Controller instance
1191 *
1192 * Return: Value of the 'discovered' flag of @c
1193 */
1194 bool nvme_ctrl_is_discovered(nvme_ctrl_t c);
1195
1196 /**
1197 * nvme_ctrl_set_persistent() - Set the 'persistent' flag
1198 * @c: Controller instance
1199 * @persistent: value of the 'persistent' flag
1200 *
1201 * Set the 'persistent' flag of @c to @persistent
1202 */
1203 void nvme_ctrl_set_persistent(nvme_ctrl_t c, bool persistent);
1204
1205 /**
1206 * nvme_ctrl_is_persistent() - Returns the value of the 'persistent' flag
1207 * @c: Controller instance
1208 *
1209 * Return: Value of the 'persistent' flag of @c
1210 */
1211 bool nvme_ctrl_is_persistent(nvme_ctrl_t c);
1212
1213 /**
1214 * nvme_ctrl_set_discovery_ctrl() - Set the 'discovery_ctrl' flag
1215 * @c: Controller to be modified
1216 * @discovery: value of the discovery_ctrl flag
1217 *
1218 * Sets the 'discovery_ctrl' flag in @c to specify whether
1219 * @c connects to a discovery subsystem.
1220 *
1221 */
1222 void nvme_ctrl_set_discovery_ctrl(nvme_ctrl_t c, bool discovery);
1223
1224 /**
1225 * nvme_ctrl_is_discovery_ctrl() - Check the 'discovery_ctrl' flag
1226 * @c: Controller to be checked
1227 *
1228 * Returns the value of the 'discovery_ctrl' flag which specifies whether
1229 * @c connects to a discovery subsystem.
1230 *
1231 * Return: Value of the 'discover_ctrl' flag
1232 */
1233 bool nvme_ctrl_is_discovery_ctrl(nvme_ctrl_t c);
1234
1235 /**
1236 * nvme_ctrl_set_unique_discovery_ctrl() - Set the 'unique_discovery_ctrl' flag
1237 * @c: Controller to be modified
1238 * @unique: value of the unique_disc_ctrl flag
1239 *
1240 * Sets the 'unique_discovery_ctrl' flag in @c to specify wheter
1241 * @c is a unique discovery controller
1242 *
1243 */
1244 void nvme_ctrl_set_unique_discovery_ctrl(nvme_ctrl_t c, bool unique);
1245
1246 /**
1247 * nvme_ctrl_is_unique_discovery_ctrl() - Check the 'unique_discovery_ctrl' flag
1248 * @c: Controller to be checked
1249 *
1250 * Return: Value of the 'unique_discovery_ctrl' flag
1251 */
1252 bool nvme_ctrl_is_unique_discovery_ctrl(nvme_ctrl_t c);
1253
1254 /**
1255 * nvme_ctrl_identify() - Issues an 'identify controller' command
1256 * @c: Controller instance
1257 * @id: Identify controller data structure
1258 *
1259 * Issues an 'identify controller' command to @c and copies the
1260 * data into @id.
1261 *
1262 * Return: 0 on success or -1 on failure.
1263 */
1264 int nvme_ctrl_identify(nvme_ctrl_t c, struct nvme_id_ctrl *id);
1265
1266 /**
1267 * nvme_disconnect_ctrl() - Disconnect a controller
1268 * @c: Controller instance
1269 *
1270 * Issues a 'disconnect' fabrics command to @c
1271 *
1272 * Return: 0 on success, -1 on failure.
1273 */
1274 int nvme_disconnect_ctrl(nvme_ctrl_t c);
1275
1276 /**
1277 * nvme_scan_ctrl() - Scan on a controller
1278 * @r: nvme_root_t object
1279 * @name: Name of the controller
1280 *
1281 * Scans a controller with sysfs name @name and add it to @r.
1282 *
1283 * Return: nvme_ctrl_t object
1284 */
1285 nvme_ctrl_t nvme_scan_ctrl(nvme_root_t r, const char *name);
1286
1287 /**
1288 * nvme_rescan_ctrl() - Rescan an existing controller
1289 * @c: Controller instance
1290 */
1291 void nvme_rescan_ctrl(nvme_ctrl_t c);
1292
1293 /**
1294 * nvme_init_ctrl() - Initialize nvme_ctrl_t object for an existing controller.
1295 * @h: nvme_host_t object
1296 * @c: nvme_ctrl_t object
1297 * @instance: Instance number (e.g. 1 for nvme1)
1298 *
1299 * Return: The ioctl() return code. Typically 0 on success.
1300 */
1301 int nvme_init_ctrl(nvme_host_t h, nvme_ctrl_t c, int instance);
1302
1303 /**
1304 * nvme_free_ctrl() - Free controller
1305 * @c: Controller instance
1306 */
1307 void nvme_free_ctrl(struct nvme_ctrl *c);
1308
1309 /**
1310 * nvme_unlink_ctrl() - Unlink controller
1311 * @c: Controller instance
1312 */
1313 void nvme_unlink_ctrl(struct nvme_ctrl *c);
1314
1315 /**
1316 * nvme_subsystem_get_nqn() - Retrieve NQN from subsystem
1317 * @s: nvme_subsystem_t object
1318 *
1319 * Return: NQN of subsystem
1320 */
1321 const char *nvme_subsystem_get_nqn(nvme_subsystem_t s);
1322
1323 /**
1324 * nvme_subsystem_get_sysfs_dir() - sysfs directory of an nvme_subsystem_t object
1325 * @s: nvme_subsystem_t object
1326 *
1327 * Return: sysfs directory name of @s
1328 */
1329 const char *nvme_subsystem_get_sysfs_dir(nvme_subsystem_t s);
1330
1331 /**
1332 * nvme_subsystem_get_name() - sysfs name of an nvme_subsystem_t object
1333 * @s: nvme_subsystem_t object
1334 *
1335 * Return: sysfs name of @s
1336 */
1337 const char *nvme_subsystem_get_name(nvme_subsystem_t s);
1338
1339 /**
1340 * nvme_subsystem_get_type() - Returns the type of a subsystem
1341 * @s: nvme_subsystem_t object
1342 *
1343 * Returns the subsystem type of @s.
1344 *
1345 * Return: 'nvm' or 'discovery'
1346 */
1347 const char *nvme_subsystem_get_type(nvme_subsystem_t s);
1348
1349 /**
1350 * nvme_subsystem_get_application() - Return the application string
1351 * @s: nvme_subsystem_t object
1352 *
1353 * Return: Managing application string or NULL if not set.
1354 */
1355 const char *nvme_subsystem_get_application(nvme_subsystem_t s);
1356
1357 /**
1358 * nvme_subsystem_set_application() - Set the application string
1359 * @s: nvme_subsystem_t object
1360 * @a: application string
1361 *
1362 * Sets the managing application string for @s.
1363 */
1364 void nvme_subsystem_set_application(nvme_subsystem_t s, const char *a);
1365
1366 /**
1367 * nvme_subsystem_get_iopolicy() - Return the IO policy of subsytem
1368 * @s: nvme_subsystem_t object
1369 *
1370 * Return: IO policy used by current subsystem
1371 */
1372 const char *nvme_subsystem_get_iopolicy(nvme_subsystem_t s);
1373
1374 /**
1375 * nvme_subsystem_get_model() - Return the model of subsystem
1376 * @s: nvme_subsystem_t object
1377 *
1378 * Return: Model of the current subsystem
1379 */
1380 const char *nvme_subsystem_get_model(nvme_subsystem_t s);
1381
1382 /**
1383 * nvme_subsystem_get_serial() - Return the serial number of subsystem
1384 * @s: nvme_subsystem_t object
1385 *
1386 * Return: Serial number of the current subsystem
1387 */
1388 const char *nvme_subsystem_get_serial(nvme_subsystem_t s);
1389
1390 /**
1391 * nvme_subsystem_get_fw_rev() - Return the firmware rev of subsystem
1392 * @s: nvme_subsystem_t object
1393 *
1394 * Return: Firmware revision of the current subsystem
1395 */
1396 const char *nvme_subsystem_get_fw_rev(nvme_subsystem_t s);
1397
1398 /**
1399 * nvme_scan_topology() - Scan NVMe topology and apply filter
1400 * @r: nvme_root_t object
1401 * @f: filter to apply
1402 * @f_args: user-specified argument to @f
1403 *
1404 * Scans the NVMe topology and filters out the resulting elements
1405 * by applying @f.
1406 *
1407 * Returns: 0 on success, -1 on failure with errno set.
1408 */
1409 int nvme_scan_topology(nvme_root_t r, nvme_scan_filter_t f, void *f_args);
1410
1411 /**
1412 * nvme_host_get_hostnqn() - Host NQN of an nvme_host_t object
1413 * @h: nvme_host_t object
1414 *
1415 * Return: Host NQN of @h
1416 */
1417 const char *nvme_host_get_hostnqn(nvme_host_t h);
1418
1419 /**
1420 * nvme_host_get_hostid() - Host ID of an nvme_host_t object
1421 * @h: nvme_host_t object
1422 *
1423 * Return: Host ID of @h
1424 */
1425 const char *nvme_host_get_hostid(nvme_host_t h);
1426
1427 /**
1428 * nvme_host_release_fds() - Close all opened file descriptors under host
1429 * @h: nvme_host_t object
1430 *
1431 * Controller and Namespace objects cache the file descriptors
1432 * of opened nvme devices. This API can be used to close and
1433 * clear all cached fds under this host.
1434 */
1435 void nvme_host_release_fds(struct nvme_host *h);
1436
1437 /**
1438 * nvme_free_host() - Free nvme_host_t object
1439 * @h: nvme_host_t object
1440 */
1441 void nvme_free_host(nvme_host_t h);
1442
1443 /**
1444 * nvme_scan() - Scan NVMe topology
1445 * @config_file: Configuration file
1446 *
1447 * Return: nvme_root_t object of found elements
1448 */
1449 nvme_root_t nvme_scan(const char *config_file);
1450
1451 /**
1452 * nvme_read_config() - Read NVMe JSON configuration file
1453 * @r: nvme_root_t object
1454 * @config_file: JSON configuration file
1455 *
1456 * Read in the contents of @config_file and merge them with
1457 * the elements in @r.
1458 *
1459 * Returns: 0 on success, -1 on failure with errno set.
1460 */
1461 int nvme_read_config(nvme_root_t r, const char *config_file);
1462
1463 /**
1464 * nvme_refresh_topology() - Refresh nvme_root_t object contents
1465 * @r: nvme_root_t object
1466 *
1467 * Removes all elements in @r and rescans the existing topology.
1468 */
1469 void nvme_refresh_topology(nvme_root_t r);
1470
1471 /**
1472 * nvme_update_config() - Update JSON configuration
1473 * @r: nvme_root_t object
1474 *
1475 * Updates the JSON configuration file with the contents of @r.
1476 *
1477 * Return: 0 on success, -1 on failure.
1478 */
1479 int nvme_update_config(nvme_root_t r);
1480
1481 /**
1482 * nvme_dump_config() - Print the JSON configuration
1483 * @r: nvme_root_t object
1484 *
1485 * Prints the current contents of the JSON configuration
1486 * file to stdout.
1487 *
1488 * Return: 0 on success, -1 on failure.
1489 */
1490 int nvme_dump_config(nvme_root_t r);
1491
1492 /**
1493 * nvme_dump_tree() - Dump internal object tree
1494 * @r: nvme_root_t object
1495 *
1496 * Prints the internal object tree in JSON format
1497 * to stdout.
1498 *
1499 * Return: 0 on success, -1 on failure.
1500 */
1501 int nvme_dump_tree(nvme_root_t r);
1502
1503 /**
1504 * nvme_get_attr() - Read sysfs attribute
1505 * @d: sysfs directory
1506 * @attr: sysfs attribute name
1507 *
1508 * Return: String with the contents of @attr or %NULL in case of an empty value
1509 * or in case of an error (indicated by non-zero errno code).
1510 */
1511 char *nvme_get_attr(const char *d, const char *attr);
1512
1513 /**
1514 * nvme_get_subsys_attr() - Read subsystem sysfs attribute
1515 * @s: nvme_subsystem_t object
1516 * @attr: sysfs attribute name
1517 *
1518 * Return: String with the contents of @attr or %NULL in case of an empty value
1519 * or in case of an error (indicated by non-zero errno code).
1520 */
1521 char *nvme_get_subsys_attr(nvme_subsystem_t s, const char *attr);
1522
1523 /**
1524 * nvme_get_ctrl_attr() - Read controller sysfs attribute
1525 * @c: Controller instance
1526 * @attr: sysfs attribute name
1527 *
1528 * Return: String with the contents of @attr or %NULL in case of an empty value
1529 * or in case of an error (indicated by non-zero errno code).
1530 */
1531 char *nvme_get_ctrl_attr(nvme_ctrl_t c, const char *attr);
1532
1533 /**
1534 * nvme_get_ns_attr() - Read namespace sysfs attribute
1535 * @n: nvme_ns_t object
1536 * @attr: sysfs attribute name
1537 *
1538 * Return: String with the contents of @attr or %NULL in case of an empty value
1539 * or in case of an error (indicated by non-zero errno code).
1540 */
1541 char *nvme_get_ns_attr(nvme_ns_t n, const char *attr);
1542
1543 /**
1544 * nvme_subsystem_lookup_namespace() - lookup namespace by NSID
1545 * @s: nvme_subsystem_t object
1546 * @nsid: Namespace id
1547 *
1548 * Return: nvme_ns_t of the namespace with id @nsid in subsystem @s
1549 */
1550 nvme_ns_t nvme_subsystem_lookup_namespace(struct nvme_subsystem *s,
1551 __u32 nsid);
1552
1553 /**
1554 * nvme_subsystem_release_fds() - Close all opened fds under subsystem
1555 * @s: nvme_subsystem_t object
1556 *
1557 * Controller and Namespace objects cache the file descriptors
1558 * of opened nvme devices. This API can be used to close and
1559 * clear all cached fds under this subsystem.
1560 *
1561 */
1562 void nvme_subsystem_release_fds(struct nvme_subsystem *s);
1563
1564
1565 /**
1566 * nvme_get_path_attr() - Read path sysfs attribute
1567 * @p: nvme_path_t object
1568 * @attr: sysfs attribute name
1569 *
1570 * Return: String with the contents of @attr or %NULL in case of an empty value
1571 * or in case of an error (indicated by non-zero errno code).
1572 */
1573 char *nvme_get_path_attr(nvme_path_t p, const char *attr);
1574
1575 /**
1576 * nvme_scan_namespace() - scan namespace based on sysfs name
1577 * @name: sysfs name of the namespace to scan
1578 *
1579 * Return: nvme_ns_t object or NULL if not found.
1580 */
1581 nvme_ns_t nvme_scan_namespace(const char *name);
1582
1583 /**
1584 * nvme_host_get_hostsymname() - Get the host's symbolic name
1585 * @h: Host for which the symbolic name should be returned.
1586 *
1587 * Return: The symbolic name or NULL if a symbolic name hasn't been
1588 * configure.
1589 */
1590 const char *nvme_host_get_hostsymname(nvme_host_t h);
1591
1592 /**
1593 * nvme_host_set_hostsymname() - Set the host's symbolic name
1594 * @h: Host for which the symbolic name should be set.
1595 * @hostsymname: Symbolic name
1596 */
1597 void nvme_host_set_hostsymname(nvme_host_t h, const char *hostsymname);
1598
1599 #endif /* _LIBNVME_TREE_H */