Line data Source code
1 : /* SPDX-License-Identifier: BSD-3-Clause
2 : * Copyright (C) 2015 Intel Corporation. All rights reserved.
3 : * Copyright (c) 2019-2021 Mellanox Technologies LTD. All rights reserved.
4 : * Copyright (c) 2021-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
5 : * Copyright (c) 2023 Samsung Electronics Co., Ltd. All rights reserved.
6 : */
7 :
8 : /** \file
9 : * NVMe driver public API
10 : */
11 :
12 : #ifndef SPDK_NVME_H
13 : #define SPDK_NVME_H
14 :
15 : #include "spdk/stdinc.h"
16 :
17 : #ifdef __cplusplus
18 : extern "C" {
19 : #endif
20 :
21 : #include "spdk/dma.h"
22 : #include "spdk/env.h"
23 : #include "spdk/keyring.h"
24 : #include "spdk/nvme_spec.h"
25 : #include "spdk/nvmf_spec.h"
26 :
27 : #define SPDK_NVME_TRANSPORT_NAME_FC "FC"
28 : #define SPDK_NVME_TRANSPORT_NAME_PCIE "PCIE"
29 : #define SPDK_NVME_TRANSPORT_NAME_RDMA "RDMA"
30 : #define SPDK_NVME_TRANSPORT_NAME_TCP "TCP"
31 : #define SPDK_NVME_TRANSPORT_NAME_VFIOUSER "VFIOUSER"
32 : #define SPDK_NVME_TRANSPORT_NAME_CUSTOM "CUSTOM"
33 :
34 : #define SPDK_NVMF_PRIORITY_MAX_LEN 4
35 :
36 : /**
37 : * Opaque handle to a controller. Returned by spdk_nvme_probe()'s attach_cb.
38 : */
39 : struct spdk_nvme_ctrlr;
40 :
41 : /**
42 : * NVMe controller initialization options.
43 : *
44 : * A pointer to this structure will be provided for each probe callback from spdk_nvme_probe() to
45 : * allow the user to request non-default options, and the actual options enabled on the controller
46 : * will be provided during the attach callback.
47 : */
48 : struct spdk_nvme_ctrlr_opts {
49 : /**
50 : * Number of I/O queues to request (used to set Number of Queues feature)
51 : */
52 : uint32_t num_io_queues;
53 :
54 : /**
55 : * Enable submission queue in controller memory buffer
56 : */
57 : bool use_cmb_sqs;
58 :
59 : /**
60 : * Don't initiate shutdown processing
61 : */
62 : bool no_shn_notification;
63 :
64 : /**
65 : * Enable interrupts for completion notification. This is only supported within a primary
66 : * SPDK process, and if enabled SPDK will not support secondary processes.
67 : */
68 : bool enable_interrupts;
69 :
70 : /* Hole at byte 7. */
71 : uint8_t reserved7;
72 :
73 : /**
74 : * Type of arbitration mechanism
75 : */
76 : enum spdk_nvme_cc_ams arb_mechanism;
77 :
78 : /**
79 : * Maximum number of commands that the controller may launch at one time. The
80 : * value is expressed as a power of two, valid values are from 0-7, and 7 means
81 : * unlimited.
82 : */
83 : uint8_t arbitration_burst;
84 :
85 : /**
86 : * Number of commands that may be executed from the low priority queue in each
87 : * arbitration round. This field is only valid when arb_mechanism is set to
88 : * SPDK_NVME_CC_AMS_WRR (weighted round robin).
89 : */
90 : uint8_t low_priority_weight;
91 :
92 : /**
93 : * Number of commands that may be executed from the medium priority queue in each
94 : * arbitration round. This field is only valid when arb_mechanism is set to
95 : * SPDK_NVME_CC_AMS_WRR (weighted round robin).
96 : */
97 : uint8_t medium_priority_weight;
98 :
99 : /**
100 : * Number of commands that may be executed from the high priority queue in each
101 : * arbitration round. This field is only valid when arb_mechanism is set to
102 : * SPDK_NVME_CC_AMS_WRR (weighted round robin).
103 : */
104 : uint8_t high_priority_weight;
105 :
106 : /**
107 : * Keep alive timeout in milliseconds (0 = disabled).
108 : *
109 : * The NVMe library will set the Keep Alive Timer feature to this value and automatically
110 : * send Keep Alive commands as needed. The library user must call
111 : * spdk_nvme_ctrlr_process_admin_completions() periodically to ensure Keep Alive commands
112 : * are sent.
113 : */
114 : uint32_t keep_alive_timeout_ms;
115 :
116 : /**
117 : * Specify the retry number when there is issue with the transport
118 : */
119 : uint8_t transport_retry_count;
120 :
121 : /* Hole at bytes 21-23. */
122 : uint8_t reserved21[3];
123 :
124 : /**
125 : * The queue depth of each NVMe I/O queue.
126 : */
127 : uint32_t io_queue_size;
128 :
129 : /**
130 : * The host NQN to use when connecting to NVMe over Fabrics controllers.
131 : *
132 : * If empty, a default value will be used.
133 : */
134 : char hostnqn[SPDK_NVMF_NQN_MAX_LEN + 1];
135 :
136 : /**
137 : * The number of requests to allocate for each NVMe I/O queue.
138 : *
139 : * This should be at least as large as io_queue_size.
140 : *
141 : * A single I/O may allocate more than one request, since splitting may be necessary to
142 : * conform to the device's maximum transfer size, PRP list compatibility requirements,
143 : * or driver-assisted striping.
144 : */
145 : uint32_t io_queue_requests;
146 :
147 : /**
148 : * Source address for NVMe-oF connections.
149 : * Set src_addr and src_svcid to empty strings if no source address should be
150 : * specified.
151 : */
152 : char src_addr[SPDK_NVMF_TRADDR_MAX_LEN + 1];
153 :
154 : /**
155 : * Source service ID (port) for NVMe-oF connections.
156 : * Set src_addr and src_svcid to empty strings if no source address should be
157 : * specified.
158 : */
159 : char src_svcid[SPDK_NVMF_TRSVCID_MAX_LEN + 1];
160 :
161 : /**
162 : * The host identifier to use when connecting to controllers with 64-bit host ID support.
163 : *
164 : * Set to all zeroes to specify that no host ID should be provided to the controller.
165 : */
166 : uint8_t host_id[8];
167 :
168 : /**
169 : * The host identifier to use when connecting to controllers with extended (128-bit) host ID support.
170 : *
171 : * Set to all zeroes to specify that no host ID should be provided to the controller.
172 : */
173 : uint8_t extended_host_id[16];
174 :
175 : /* Hole at bytes 570-571. */
176 : uint8_t reserved570[2];
177 :
178 : /**
179 : * The I/O command set to select.
180 : *
181 : * If the requested command set is not supported, the controller
182 : * initialization process will not proceed. By default, the NVM
183 : * command set is used.
184 : */
185 : enum spdk_nvme_cc_css command_set;
186 :
187 : /**
188 : * Admin commands timeout in milliseconds (0 = no timeout).
189 : *
190 : * The timeout value is used for admin commands submitted internally
191 : * by the nvme driver during initialization, before the user is able
192 : * to call spdk_nvme_ctrlr_register_timeout_callback(). By default,
193 : * this is set to 120 seconds, users can change it in the probing
194 : * callback.
195 : */
196 : uint32_t admin_timeout_ms;
197 :
198 : /**
199 : * It is used for TCP transport.
200 : *
201 : * Set to true, means having header digest for the header in the NVMe/TCP PDU
202 : */
203 : bool header_digest;
204 :
205 : /**
206 : * It is used for TCP transport.
207 : *
208 : * Set to true, means having data digest for the data in the NVMe/TCP PDU
209 : */
210 : bool data_digest;
211 :
212 : /**
213 : * Disable logging of requests that are completed with error status.
214 : *
215 : * Defaults to 'false' (errors are logged).
216 : */
217 : bool disable_error_logging;
218 :
219 : /**
220 : * It is used for both RDMA & TCP transport
221 : * Specify the transport ACK timeout. The value should be in range 0-31 where 0 means
222 : * use driver-specific default value.
223 : * RDMA: The value is applied to each qpair
224 : * and affects the time that qpair waits for transport layer acknowledgement
225 : * until it retransmits a packet. The value should be chosen empirically
226 : * to meet the needs of a particular application. A low value means less time
227 : * the qpair waits for ACK which can increase the number of retransmissions.
228 : * A large value can increase the time the connection is closed.
229 : * The value of ACK timeout is calculated according to the formula
230 : * 4.096 * 2^(transport_ack_timeout) usec.
231 : * TCP: The value is applied to each qpair
232 : * and affects the time that qpair waits for transport layer acknowledgement
233 : * until connection is closed forcefully.
234 : * The value of ACK timeout is calculated according to the formula
235 : * 2^(transport_ack_timeout) msec.
236 : */
237 : uint8_t transport_ack_timeout;
238 :
239 : /**
240 : * The queue depth of NVMe Admin queue.
241 : */
242 : uint16_t admin_queue_size;
243 :
244 : /* Hole at bytes 586-591. */
245 : uint8_t reserved586[6];
246 :
247 : /**
248 : * The size of spdk_nvme_ctrlr_opts according to the caller of this library is used for ABI
249 : * compatibility. The library uses this field to know how many fields in this
250 : * structure are valid. And the library will populate any remaining fields with default values.
251 : */
252 : size_t opts_size;
253 :
254 : /**
255 : * The amount of time to spend before timing out during fabric connect on qpairs associated with
256 : * this controller in microseconds.
257 : */
258 : uint64_t fabrics_connect_timeout_us;
259 :
260 : /**
261 : * Disable reading ANA log page. The upper layer should reading ANA log page instead
262 : * if set to true.
263 : *
264 : * Default is `false` (ANA log page is read).
265 : */
266 : bool disable_read_ana_log_page;
267 :
268 : /* Hole at bytes 610-616. */
269 : uint8_t reserved610[7];
270 :
271 : /**
272 : * Disable reading CHANGED_NS_LIST log page in response to an NS_ATTR_CHANGED AEN
273 : * The upper layer should reading CHANGED_NS_LIST log page instead if set to true.
274 : *
275 : * Default is `false` (CHANGED_NS_LIST log page is read).
276 : */
277 : uint8_t disable_read_changed_ns_list_log_page;
278 :
279 : /* Hole at bytes 617-816. */
280 : uint8_t reserved617[200];
281 :
282 : /**
283 : * It is used for RDMA transport.
284 : *
285 : * Set the IP protocol type of service value for RDMA transport. Default is 0, which means that the TOS will not be set.
286 : */
287 : uint8_t transport_tos;
288 :
289 : /**
290 : * Pre-shared key for NVMe/TCP's TLS connection.
291 : */
292 : struct spdk_key *tls_psk;
293 :
294 : /**
295 : * In-band authentication DH-HMAC-CHAP host key.
296 : */
297 : struct spdk_key *dhchap_key;
298 :
299 : /**
300 : * In-band authentication DH-HMAC-CHAP controller key.
301 : */
302 : struct spdk_key *dhchap_ctrlr_key;
303 :
304 : /**
305 : * Allowed digests in in-band authentication. Each bit corresponds to one of the
306 : * spdk_nvmf_dhchap_hash values.
307 : */
308 : uint32_t dhchap_digests;
309 :
310 : /**
311 : * Allowed Diffie-Hellman groups in in-band authentication. Each bit corresponds to one of
312 : * the spdk_nvmf_dhchap_dhgroup values.
313 : */
314 : uint32_t dhchap_dhgroups;
315 : };
316 : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_ctrlr_opts) == 856, "Incorrect size");
317 :
318 : /**
319 : * NVMe acceleration operation callback.
320 : *
321 : * \param cb_arg The user provided arg which is passed to the corresponding accelerated function call
322 : * defined in struct spdk_nvme_accel_fn_table.
323 : * \param status 0 if it completed successfully, or negative errno if it failed.
324 : */
325 : typedef void (*spdk_nvme_accel_completion_cb)(void *cb_arg, int status);
326 :
327 : /**
328 : * Completion callback for a single operation in a sequence.
329 : *
330 : * \param cb_arg Argument provided by the user when appending an operation to a sequence.
331 : */
332 : typedef void (*spdk_nvme_accel_step_cb)(void *cb_arg);
333 :
334 : /**
335 : * Function table for the NVMe accelerator device.
336 : *
337 : * This table provides a set of APIs to allow user to leverage
338 : * accelerator functions.
339 : */
340 : struct spdk_nvme_accel_fn_table {
341 : /**
342 : * The size of spdk_nvme_accel_fun_table according to the caller of
343 : * this library is used for ABI compatibility. The library uses this
344 : * field to know how many fields in this structure are valid.
345 : * And the library will populate any remaining fields with default values.
346 : * Newly added fields should be put at the end of the struct.
347 : */
348 : size_t table_size;
349 :
350 : /* Hole at bytes 8-15. */
351 : uint8_t reserved8[8];
352 :
353 : /** Finish an accel sequence */
354 : void (*finish_sequence)(void *seq, spdk_nvme_accel_completion_cb cb_fn, void *cb_arg);
355 :
356 : /** Reverse an accel sequence */
357 : void (*reverse_sequence)(void *seq);
358 :
359 : /** Abort an accel sequence */
360 : void (*abort_sequence)(void *seq);
361 :
362 : /** Append a crc32c operation to a sequence */
363 : int (*append_crc32c)(void *ctx, void **seq, uint32_t *dst, struct iovec *iovs, uint32_t iovcnt,
364 : struct spdk_memory_domain *memory_domain, void *domain_ctx,
365 : uint32_t seed, spdk_nvme_accel_step_cb cb_fn, void *cb_arg);
366 :
367 : /** Append a copy operation to a sequence */
368 : int (*append_copy)(void *ctx, void **seq, struct iovec *dst_iovs, uint32_t dst_iovcnt,
369 : struct spdk_memory_domain *dst_domain, void *dst_domain_ctx,
370 : struct iovec *src_iovs, uint32_t src_iovcnt,
371 : struct spdk_memory_domain *src_domain, void *src_domain_ctx,
372 : spdk_nvme_accel_step_cb cb_fn, void *cb_arg);
373 : };
374 :
375 : /**
376 : * Indicate whether a ctrlr handle is associated with a Discovery controller.
377 : *
378 : * \param ctrlr Opaque handle to NVMe controller.
379 : *
380 : * \return true if a discovery controller, else false.
381 : */
382 : bool spdk_nvme_ctrlr_is_discovery(struct spdk_nvme_ctrlr *ctrlr);
383 :
384 : /**
385 : * Indicate whether a ctrlr handle is associated with a fabrics controller.
386 : *
387 : * \param ctrlr Opaque handle to NVMe controller.
388 : *
389 : * \return true if a fabrics controller, else false.
390 : */
391 : bool spdk_nvme_ctrlr_is_fabrics(struct spdk_nvme_ctrlr *ctrlr);
392 :
393 : /**
394 : * Get the default options for the creation of a specific NVMe controller.
395 : *
396 : * \param[out] opts Will be filled with the default option.
397 : * \param opts_size Must be set to sizeof(struct spdk_nvme_ctrlr_opts).
398 : */
399 : void spdk_nvme_ctrlr_get_default_ctrlr_opts(struct spdk_nvme_ctrlr_opts *opts,
400 : size_t opts_size);
401 :
402 : /*
403 : * Get the options in use for a given controller.
404 : *
405 : * \param ctrlr Opaque handle to NVMe controller.
406 : */
407 : const struct spdk_nvme_ctrlr_opts *spdk_nvme_ctrlr_get_opts(struct spdk_nvme_ctrlr *ctrlr);
408 :
409 : /**
410 : * Reason for qpair disconnect at the transport layer.
411 : *
412 : * NONE implies that the qpair is still connected while UNKNOWN means that the
413 : * qpair is disconnected, but the cause was not apparent.
414 : */
415 : enum spdk_nvme_qp_failure_reason {
416 : SPDK_NVME_QPAIR_FAILURE_NONE = 0,
417 : SPDK_NVME_QPAIR_FAILURE_LOCAL,
418 : SPDK_NVME_QPAIR_FAILURE_REMOTE,
419 : SPDK_NVME_QPAIR_FAILURE_UNKNOWN,
420 : SPDK_NVME_QPAIR_FAILURE_RESET,
421 : };
422 :
423 : typedef enum spdk_nvme_qp_failure_reason spdk_nvme_qp_failure_reason;
424 :
425 : /**
426 : * NVMe library transports
427 : *
428 : * NOTE: These are mapped directly to the NVMe over Fabrics TRTYPE values, except for PCIe,
429 : * which is a special case since NVMe over Fabrics does not define a TRTYPE for local PCIe.
430 : *
431 : * Currently, this uses 256 for PCIe which is intentionally outside of the 8-bit range of TRTYPE.
432 : * If the NVMe-oF specification ever defines a PCIe TRTYPE, this should be updated.
433 : */
434 : enum spdk_nvme_transport_type {
435 : /**
436 : * PCIe Transport (locally attached devices)
437 : */
438 : SPDK_NVME_TRANSPORT_PCIE = 256,
439 :
440 : /**
441 : * RDMA Transport (RoCE, iWARP, etc.)
442 : */
443 : SPDK_NVME_TRANSPORT_RDMA = SPDK_NVMF_TRTYPE_RDMA,
444 :
445 : /**
446 : * Fibre Channel (FC) Transport
447 : */
448 : SPDK_NVME_TRANSPORT_FC = SPDK_NVMF_TRTYPE_FC,
449 :
450 : /**
451 : * TCP Transport
452 : */
453 : SPDK_NVME_TRANSPORT_TCP = SPDK_NVMF_TRTYPE_TCP,
454 :
455 : /**
456 : * Custom VFIO User Transport (Not spec defined)
457 : */
458 : SPDK_NVME_TRANSPORT_VFIOUSER = 1024,
459 :
460 : /**
461 : * Custom Transport (Not spec defined)
462 : */
463 : SPDK_NVME_TRANSPORT_CUSTOM = 4096,
464 :
465 : /**
466 : * Custom Fabric Transport (Not spec defined)
467 : */
468 : SPDK_NVME_TRANSPORT_CUSTOM_FABRICS = 4097,
469 : };
470 :
471 291 : static inline bool spdk_nvme_trtype_is_fabrics(enum spdk_nvme_transport_type trtype)
472 : {
473 : /* We always define non-fabrics trtypes outside of the 8-bit range
474 : * of NVMe-oF trtype.
475 : */
476 291 : return trtype <= UINT8_MAX || trtype == SPDK_NVME_TRANSPORT_CUSTOM_FABRICS;
477 : }
478 :
479 : /* typedef added for coding style reasons */
480 : typedef enum spdk_nvme_transport_type spdk_nvme_transport_type_t;
481 :
482 : /**
483 : * NVMe transport identifier.
484 : *
485 : * This identifies a unique endpoint on an NVMe fabric.
486 : *
487 : * A string representation of a transport ID may be converted to this type using
488 : * spdk_nvme_transport_id_parse().
489 : */
490 : struct spdk_nvme_transport_id {
491 : /**
492 : * NVMe transport string.
493 : */
494 : char trstring[SPDK_NVMF_TRSTRING_MAX_LEN + 1];
495 :
496 : /**
497 : * NVMe transport type.
498 : */
499 : enum spdk_nvme_transport_type trtype;
500 :
501 : /**
502 : * Address family of the transport address.
503 : *
504 : * For PCIe, this value is ignored.
505 : */
506 : enum spdk_nvmf_adrfam adrfam;
507 :
508 : /**
509 : * Transport address of the NVMe-oF endpoint. For transports which use IP
510 : * addressing (e.g. RDMA), this should be an IP address. For PCIe, this
511 : * can either be a zero length string (the whole bus) or a PCI address
512 : * in the format DDDD:BB:DD.FF or DDDD.BB.DD.FF. For FC the string is
513 : * formatted as: nn-0xWWNN:pn-0xWWPN” where WWNN is the Node_Name of the
514 : * target NVMe_Port and WWPN is the N_Port_Name of the target NVMe_Port.
515 : */
516 : char traddr[SPDK_NVMF_TRADDR_MAX_LEN + 1];
517 :
518 : /**
519 : * Transport service id of the NVMe-oF endpoint. For transports which use
520 : * IP addressing (e.g. RDMA), this field should be the port number. For PCIe,
521 : * and FC this is always a zero length string.
522 : */
523 : char trsvcid[SPDK_NVMF_TRSVCID_MAX_LEN + 1];
524 :
525 : /**
526 : * Subsystem NQN of the NVMe over Fabrics endpoint. May be a zero length string.
527 : */
528 : char subnqn[SPDK_NVMF_NQN_MAX_LEN + 1];
529 :
530 : /**
531 : * The Transport connection priority of the NVMe-oF endpoint. Currently this is
532 : * only supported by posix based sock implementation on Kernel TCP stack. More
533 : * information of this field can be found from the socket(7) man page.
534 : */
535 : int priority;
536 : };
537 :
538 : /**
539 : * NVMe host identifier
540 : *
541 : * Used for defining the host identity for an NVMe-oF connection.
542 : *
543 : * In terms of configuration, this object can be considered a subtype of TransportID
544 : * Please see etc/spdk/nvmf.conf.in for more details.
545 : *
546 : * A string representation of this type may be converted to this type using
547 : * spdk_nvme_host_id_parse().
548 : */
549 : struct spdk_nvme_host_id {
550 : /**
551 : * Transport address to be used by the host when connecting to the NVMe-oF endpoint.
552 : * May be an IP address or a zero length string for transports which
553 : * use IP addressing (e.g. RDMA).
554 : * For PCIe and FC this is always a zero length string.
555 : */
556 : char hostaddr[SPDK_NVMF_TRADDR_MAX_LEN + 1];
557 :
558 : /**
559 : * Transport service ID used by the host when connecting to the NVMe.
560 : * May be a port number or a zero length string for transports which
561 : * use IP addressing (e.g. RDMA).
562 : * For PCIe and FC this is always a zero length string.
563 : */
564 : char hostsvcid[SPDK_NVMF_TRSVCID_MAX_LEN + 1];
565 : };
566 :
567 : struct spdk_nvme_rdma_device_stat {
568 : const char *name;
569 : uint64_t polls;
570 : uint64_t idle_polls;
571 : uint64_t completions;
572 : uint64_t queued_requests;
573 : uint64_t total_send_wrs;
574 : uint64_t send_doorbell_updates;
575 : uint64_t total_recv_wrs;
576 : uint64_t recv_doorbell_updates;
577 : };
578 :
579 : struct spdk_nvme_pcie_stat {
580 : uint64_t polls;
581 : uint64_t idle_polls;
582 : uint64_t completions;
583 : uint64_t cq_mmio_doorbell_updates;
584 : uint64_t cq_shadow_doorbell_updates;
585 : uint64_t submitted_requests;
586 : uint64_t queued_requests;
587 : uint64_t sq_mmio_doorbell_updates;
588 : uint64_t sq_shadow_doorbell_updates;
589 : };
590 :
591 : struct spdk_nvme_tcp_stat {
592 : uint64_t polls;
593 : uint64_t idle_polls;
594 : uint64_t socket_completions;
595 : uint64_t nvme_completions;
596 : uint64_t submitted_requests;
597 : uint64_t queued_requests;
598 : };
599 :
600 : struct spdk_nvme_transport_poll_group_stat {
601 : spdk_nvme_transport_type_t trtype;
602 : union {
603 : struct {
604 : uint32_t num_devices;
605 : struct spdk_nvme_rdma_device_stat *device_stats;
606 : } rdma;
607 : struct spdk_nvme_pcie_stat pcie;
608 : struct spdk_nvme_tcp_stat tcp;
609 : };
610 : };
611 :
612 : struct spdk_nvme_poll_group_stat {
613 : uint32_t num_transports;
614 : struct spdk_nvme_transport_poll_group_stat **transport_stat;
615 : };
616 :
617 : /*
618 : * Controller support flags
619 : *
620 : * Used for identifying if the controller supports these flags.
621 : */
622 : enum spdk_nvme_ctrlr_flags {
623 : SPDK_NVME_CTRLR_SGL_SUPPORTED = 1 << 0, /**< SGL is supported */
624 : SPDK_NVME_CTRLR_SECURITY_SEND_RECV_SUPPORTED = 1 << 1, /**< security send/receive is supported */
625 : SPDK_NVME_CTRLR_WRR_SUPPORTED = 1 << 2, /**< Weighted Round Robin is supported */
626 : SPDK_NVME_CTRLR_COMPARE_AND_WRITE_SUPPORTED = 1 << 3, /**< Compare and write fused operations supported */
627 : SPDK_NVME_CTRLR_SGL_REQUIRES_DWORD_ALIGNMENT = 1 << 4, /**< Dword alignment is required for SGL */
628 : SPDK_NVME_CTRLR_ZONE_APPEND_SUPPORTED = 1 << 5, /**< Zone Append is supported (within Zoned Namespaces) */
629 : SPDK_NVME_CTRLR_DIRECTIVES_SUPPORTED = 1 << 6, /**< The Directives is supported */
630 : SPDK_NVME_CTRLR_MPTR_SGL_SUPPORTED = 1 << 7, /**< MPTR containing SGL descriptor is supported */
631 : SPDK_NVME_CTRLR_ACCEL_SEQUENCE_SUPPORTED = 1 << 8, /**< Support for sending I/O requests with accel sequence */
632 : };
633 :
634 : /**
635 : * Structure with optional IO request parameters
636 : */
637 : struct spdk_nvme_ns_cmd_ext_io_opts {
638 : /** size of this structure in bytes, use SPDK_SIZEOF(opts, last_member) to obtain it */
639 : size_t size;
640 : /** Memory domain which describes data payload in IO request. The controller must support
641 : * the corresponding memory domain type, refer to \ref spdk_nvme_ctrlr_get_memory_domains */
642 : struct spdk_memory_domain *memory_domain;
643 : /** User context to be passed to memory domain operations */
644 : void *memory_domain_ctx;
645 : /** Flags for this IO, defined in nvme_spec.h */
646 : uint32_t io_flags;
647 : /* Hole at bytes 28-31. */
648 : uint8_t reserved28[4];
649 : /** Virtual address pointer to the metadata payload, the length of metadata is specified by \ref spdk_nvme_ns_get_md_size */
650 : void *metadata;
651 : /** Application tag mask to use end-to-end protection information. */
652 : uint16_t apptag_mask;
653 : /** Application tag to use end-to-end protection information. */
654 : uint16_t apptag;
655 : /** Command dword 13 specific field. */
656 : uint32_t cdw13;
657 : /** Accel sequence (only valid if SPDK_NVME_CTRLR_ACCEL_SEQUENCE_SUPPORTED is set and the
658 : * qpair is part of a poll group).
659 : */
660 : void *accel_sequence;
661 : };
662 : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_ns_cmd_ext_io_opts) == 56, "Incorrect size");
663 :
664 : /**
665 : * Parse the string representation of a transport ID.
666 : *
667 : * \param trid Output transport ID structure (must be allocated and initialized by caller).
668 : * \param str Input string representation of a transport ID to parse.
669 : *
670 : * str must be a zero-terminated C string containing one or more key:value pairs
671 : * separated by whitespace.
672 : *
673 : * Key | Value
674 : * ------------ | -----
675 : * trtype | Transport type (e.g. PCIe, RDMA)
676 : * adrfam | Address family (e.g. IPv4, IPv6)
677 : * traddr | Transport address (e.g. 0000:04:00.0 for PCIe, 192.168.100.8 for RDMA, or WWN for FC)
678 : * trsvcid | Transport service identifier (e.g. 4420)
679 : * subnqn | Subsystem NQN
680 : *
681 : * Unspecified fields of trid are left unmodified, so the caller must initialize
682 : * trid (for example, memset() to 0) before calling this function.
683 : *
684 : * \return 0 if parsing was successful and trid is filled out, or negated errno
685 : * values on failure.
686 : */
687 : int spdk_nvme_transport_id_parse(struct spdk_nvme_transport_id *trid, const char *str);
688 :
689 :
690 : /**
691 : * Fill in the trtype and trstring fields of this trid based on a known transport type.
692 : *
693 : * \param trid The trid to fill out.
694 : * \param trtype The transport type to use for filling the trid fields. Only valid for
695 : * transport types referenced in the NVMe-oF spec.
696 : */
697 : void spdk_nvme_trid_populate_transport(struct spdk_nvme_transport_id *trid,
698 : enum spdk_nvme_transport_type trtype);
699 :
700 : /**
701 : * Parse the string representation of a host ID.
702 : *
703 : * \param hostid Output host ID structure (must be allocated and initialized by caller).
704 : * \param str Input string representation of a transport ID to parse (hostid is a sub-configuration).
705 : *
706 : * str must be a zero-terminated C string containing one or more key:value pairs
707 : * separated by whitespace.
708 : *
709 : * Key | Value
710 : * -------------- | -----
711 : * hostaddr | Transport address (e.g. 192.168.100.8 for RDMA)
712 : * hostsvcid | Transport service identifier (e.g. 4420)
713 : *
714 : * Unspecified fields of trid are left unmodified, so the caller must initialize
715 : * hostid (for example, memset() to 0) before calling this function.
716 : *
717 : * This function should not be used with Fiber Channel or PCIe as these transports
718 : * do not require host information for connections.
719 : *
720 : * \return 0 if parsing was successful and hostid is filled out, or negated errno
721 : * values on failure.
722 : */
723 : int spdk_nvme_host_id_parse(struct spdk_nvme_host_id *hostid, const char *str);
724 :
725 : /**
726 : * Parse the string representation of a transport ID transport type into the trid struct.
727 : *
728 : * \param trid The trid to write to
729 : * \param trstring Input string representation of transport type (e.g. "PCIe", "RDMA").
730 : *
731 : * \return 0 if parsing was successful and trtype is filled out, or negated errno
732 : * values if the provided string was an invalid transport string.
733 : */
734 : int spdk_nvme_transport_id_populate_trstring(struct spdk_nvme_transport_id *trid,
735 : const char *trstring);
736 :
737 : /**
738 : * Parse the string representation of a transport ID transport type.
739 : *
740 : * \param trtype Output transport type (allocated by caller).
741 : * \param str Input string representation of transport type (e.g. "PCIe", "RDMA").
742 : *
743 : * \return 0 if parsing was successful and trtype is filled out, or negated errno
744 : * values on failure.
745 : */
746 : int spdk_nvme_transport_id_parse_trtype(enum spdk_nvme_transport_type *trtype, const char *str);
747 :
748 : /**
749 : * Look up the string representation of a transport ID transport type.
750 : *
751 : * \param trtype Transport type to convert.
752 : *
753 : * \return static string constant describing trtype, or NULL if trtype not found.
754 : */
755 : const char *spdk_nvme_transport_id_trtype_str(enum spdk_nvme_transport_type trtype);
756 :
757 : /**
758 : * Look up the string representation of a transport ID address family.
759 : *
760 : * \param adrfam Address family to convert.
761 : *
762 : * \return static string constant describing adrfam, or NULL if adrfam not found.
763 : */
764 : const char *spdk_nvme_transport_id_adrfam_str(enum spdk_nvmf_adrfam adrfam);
765 :
766 : /**
767 : * Parse the string representation of a transport ID address family.
768 : *
769 : * \param adrfam Output address family (allocated by caller).
770 : * \param str Input string representation of address family (e.g. "IPv4", "IPv6").
771 : *
772 : * \return 0 if parsing was successful and adrfam is filled out, or negated errno
773 : * values on failure.
774 : */
775 : int spdk_nvme_transport_id_parse_adrfam(enum spdk_nvmf_adrfam *adrfam, const char *str);
776 :
777 : /**
778 : * Compare two transport IDs.
779 : *
780 : * The result of this function may be used to sort transport IDs in a consistent
781 : * order; however, the comparison result is not guaranteed to be consistent across
782 : * library versions.
783 : *
784 : * This function uses a case-insensitive comparison for string fields, but it does
785 : * not otherwise normalize the transport ID. It is the caller's responsibility to
786 : * provide the transport IDs in a consistent format.
787 : *
788 : * \param trid1 First transport ID to compare.
789 : * \param trid2 Second transport ID to compare.
790 : *
791 : * \return 0 if trid1 == trid2, less than 0 if trid1 < trid2, greater than 0 if
792 : * trid1 > trid2.
793 : */
794 : int spdk_nvme_transport_id_compare(const struct spdk_nvme_transport_id *trid1,
795 : const struct spdk_nvme_transport_id *trid2);
796 :
797 : /**
798 : * Parse the string representation of PI check settings (prchk:guard|reftag)
799 : *
800 : * \param prchk_flags Output PI check flags.
801 : * \param str Input string representation of PI check settings.
802 : *
803 : * \return 0 if parsing was successful and prchk_flags is set, or negated errno
804 : * values on failure.
805 : */
806 : int spdk_nvme_prchk_flags_parse(uint32_t *prchk_flags, const char *str);
807 :
808 : /**
809 : * Look up the string representation of PI check settings (prchk:guard|reftag)
810 : *
811 : * \param prchk_flags PI check flags to convert.
812 : *
813 : * \return static string constant describing PI check settings. If prchk_flags is 0,
814 : * NULL is returned.
815 : */
816 : const char *spdk_nvme_prchk_flags_str(uint32_t prchk_flags);
817 :
818 : /**
819 : * Determine whether the NVMe library can handle a specific NVMe over Fabrics
820 : * transport type.
821 : *
822 : * \param trtype NVMe over Fabrics transport type to check.
823 : *
824 : * \return true if trtype is supported or false if it is not supported or if
825 : * SPDK_NVME_TRANSPORT_CUSTOM is supplied as trtype since it can represent multiple
826 : * transports.
827 : */
828 : bool spdk_nvme_transport_available(enum spdk_nvme_transport_type trtype);
829 :
830 : /**
831 : * Determine whether the NVMe library can handle a specific NVMe over Fabrics
832 : * transport type.
833 : *
834 : * \param transport_name Name of the NVMe over Fabrics transport type to check.
835 : *
836 : * \return true if transport_name is supported or false if it is not supported.
837 : */
838 : bool spdk_nvme_transport_available_by_name(const char *transport_name);
839 :
840 : /**
841 : * Callback for spdk_nvme_probe() enumeration.
842 : *
843 : * \param cb_ctx Opaque value passed to spdk_nvme_probe().
844 : * \param trid NVMe transport identifier.
845 : * \param opts NVMe controller initialization options. This structure will be
846 : * populated with the default values on entry, and the user callback may update
847 : * any options to request a different value. The controller may not support all
848 : * requested parameters, so the final values will be provided during the attach
849 : * callback.
850 : *
851 : * \return true to attach to this device.
852 : */
853 : typedef bool (*spdk_nvme_probe_cb)(void *cb_ctx, const struct spdk_nvme_transport_id *trid,
854 : struct spdk_nvme_ctrlr_opts *opts);
855 :
856 : /**
857 : * Callback for spdk_nvme_attach() to report a device that has been attached to
858 : * the userspace NVMe driver.
859 : *
860 : * \param cb_ctx Opaque value passed to spdk_nvme_attach_cb().
861 : * \param trid NVMe transport identifier.
862 : * \param ctrlr Opaque handle to NVMe controller.
863 : * \param opts NVMe controller initialization options that were actually used.
864 : * Options may differ from the requested options from the attach call depending
865 : * on what the controller supports.
866 : */
867 : typedef void (*spdk_nvme_attach_cb)(void *cb_ctx, const struct spdk_nvme_transport_id *trid,
868 : struct spdk_nvme_ctrlr *ctrlr,
869 : const struct spdk_nvme_ctrlr_opts *opts);
870 :
871 : /**
872 : * Callback for spdk_nvme_probe*_ext() to report a device that has been probed but
873 : * unable to attach to the userspace NVMe driver.
874 : *
875 : * \param cb_ctx Opaque value passed to spdk_nvme_probe*_ext().
876 : * \param trid NVMe transport identifier.
877 : * \param rc Negative error code that provides information about the failure.
878 : */
879 : typedef void (*spdk_nvme_attach_fail_cb)(void *cb_ctx, const struct spdk_nvme_transport_id *trid,
880 : int rc);
881 :
882 : /**
883 : * Callback for spdk_nvme_remove() to report that a device attached to the userspace
884 : * NVMe driver has been removed from the system.
885 : *
886 : * The controller will remain in a failed state (any new I/O submitted will fail).
887 : *
888 : * The controller must be detached from the userspace driver by calling spdk_nvme_detach()
889 : * once the controller is no longer in use. It is up to the library user to ensure
890 : * that no other threads are using the controller before calling spdk_nvme_detach().
891 : *
892 : * \param cb_ctx Opaque value passed to spdk_nvme_remove_cb().
893 : * \param ctrlr NVMe controller instance that was removed.
894 : */
895 : typedef void (*spdk_nvme_remove_cb)(void *cb_ctx, struct spdk_nvme_ctrlr *ctrlr);
896 :
897 : typedef bool (*spdk_nvme_pcie_hotplug_filter_cb)(const struct spdk_pci_addr *addr);
898 :
899 : /**
900 : * Register the associated function to allow filtering of hot-inserted PCIe SSDs.
901 : *
902 : * If an application is using spdk_nvme_probe() to detect hot-inserted SSDs,
903 : * this function may be used to register a function to filter those SSDs.
904 : * If the filter function returns true, the nvme library will notify the SPDK
905 : * env layer to allow probing of the device.
906 : *
907 : * Registering a filter function is optional. If none is registered, the nvme
908 : * library will allow probing of all hot-inserted SSDs.
909 : *
910 : * \param filter_cb Filter function callback routine
911 : */
912 : void
913 : spdk_nvme_pcie_set_hotplug_filter(spdk_nvme_pcie_hotplug_filter_cb filter_cb);
914 :
915 : /**
916 : * Enumerate the bus indicated by the transport ID and attach the userspace NVMe
917 : * driver to each device found if desired.
918 : *
919 : * This function is not thread safe and should only be called from one thread at
920 : * a time while no other threads are actively using any NVMe devices.
921 : *
922 : * If called from a secondary process, only devices that have been attached to
923 : * the userspace driver in the primary process will be probed.
924 : *
925 : * If called more than once, only devices that are not already attached to the
926 : * SPDK NVMe driver will be reported.
927 : *
928 : * To stop using the the controller and release its associated resources,
929 : * call spdk_nvme_detach() with the spdk_nvme_ctrlr instance from the attach_cb()
930 : * function.
931 : *
932 : * \param trid The transport ID indicating which bus to enumerate. If the trtype
933 : * is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is
934 : * fabrics (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an
935 : * NVMe-oF discovery service.
936 : * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of
937 : * the callbacks.
938 : * \param probe_cb will be called once per NVMe device found in the system.
939 : * \param attach_cb will be called for devices for which probe_cb returned true
940 : * once that NVMe controller has been attached to the userspace driver.
941 : * \param remove_cb will be called for devices that were attached in a previous
942 : * spdk_nvme_probe() call but are no longer attached to the system. Optional;
943 : * specify NULL if removal notices are not desired.
944 : *
945 : * \return 0 on success, -1 on failure.
946 : */
947 : int spdk_nvme_probe(const struct spdk_nvme_transport_id *trid,
948 : void *cb_ctx,
949 : spdk_nvme_probe_cb probe_cb,
950 : spdk_nvme_attach_cb attach_cb,
951 : spdk_nvme_remove_cb remove_cb);
952 :
953 : /**
954 : * Enumerate the bus indicated by the transport ID and attach the userspace NVMe
955 : * driver to each device found if desired.
956 : *
957 : * This works just the same as spdk_nvme_probe(), except that it calls attach_fail_cb
958 : * for devices that are probed but unabled to attach.
959 : *
960 : * \param trid The transport ID indicating which bus to enumerate. If the trtype
961 : * is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is
962 : * fabrics (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an
963 : * NVMe-oF discovery service.
964 : * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of
965 : * the callbacks.
966 : * \param probe_cb will be called once per NVMe device found in the system.
967 : * \param attach_cb will be called for devices for which probe_cb returned true
968 : * once that NVMe controller has been attached to the userspace driver.
969 : * \param attach_fail_cb will be called for devices which probe_cb returned true
970 : * but failed to attach to the userspace driver.
971 : * \param remove_cb will be called for devices that were attached in a previous
972 : * spdk_nvme_probe() call but are no longer attached to the system. Optional;
973 : * specify NULL if removal notices are not desired.
974 : *
975 : * \return 0 on success, -1 on failure.
976 : */
977 : int spdk_nvme_probe_ext(const struct spdk_nvme_transport_id *trid,
978 : void *cb_ctx,
979 : spdk_nvme_probe_cb probe_cb,
980 : spdk_nvme_attach_cb attach_cb,
981 : spdk_nvme_attach_fail_cb attach_fail_cb,
982 : spdk_nvme_remove_cb remove_cb);
983 :
984 : /**
985 : * Connect the NVMe driver to the device located at the given transport ID.
986 : *
987 : * This function is not thread safe and should only be called from one thread at
988 : * a time while no other threads are actively using this NVMe device.
989 : *
990 : * If called from a secondary process, only the device that has been attached to
991 : * the userspace driver in the primary process will be connected.
992 : *
993 : * If connecting to multiple controllers, it is suggested to use spdk_nvme_probe()
994 : * and filter the requested controllers with the probe callback. For PCIe controllers,
995 : * spdk_nvme_probe() will be more efficient since the controller resets will happen
996 : * in parallel.
997 : *
998 : * To stop using the the controller and release its associated resources, call
999 : * spdk_nvme_detach() with the spdk_nvme_ctrlr instance returned by this function.
1000 : *
1001 : * \param trid The transport ID indicating which device to connect. If the trtype
1002 : * is PCIe, this will connect the local PCIe bus. If the trtype is fabrics
1003 : * (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an NVMe-oF
1004 : * service.
1005 : * \param opts NVMe controller initialization options. Default values will be used
1006 : * if the user does not specify the options. The controller may not support all
1007 : * requested parameters.
1008 : * \param opts_size Must be set to sizeof(struct spdk_nvme_ctrlr_opts), or 0 if
1009 : * opts is NULL.
1010 : *
1011 : * \return pointer to the connected NVMe controller or NULL if there is any failure.
1012 : *
1013 : */
1014 : struct spdk_nvme_ctrlr *spdk_nvme_connect(const struct spdk_nvme_transport_id *trid,
1015 : const struct spdk_nvme_ctrlr_opts *opts,
1016 : size_t opts_size);
1017 :
1018 : struct spdk_nvme_probe_ctx;
1019 :
1020 : /**
1021 : * Connect the NVMe driver to the device located at the given transport ID.
1022 : *
1023 : * The function will return a probe context on success, controller associates with
1024 : * the context is not ready for use, user must call spdk_nvme_probe_poll_async()
1025 : * until spdk_nvme_probe_poll_async() returns 0.
1026 : *
1027 : * \param trid The transport ID indicating which device to connect. If the trtype
1028 : * is PCIe, this will connect the local PCIe bus. If the trtype is fabrics
1029 : * (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an NVMe-oF
1030 : * service.
1031 : * \param opts NVMe controller initialization options. Default values will be used
1032 : * if the user does not specify the options. The controller may not support all
1033 : * requested parameters.
1034 : * \param attach_cb will be called once the NVMe controller has been attached
1035 : * to the userspace driver.
1036 : *
1037 : * \return probe context on success, NULL on failure.
1038 : *
1039 : */
1040 : struct spdk_nvme_probe_ctx *spdk_nvme_connect_async(const struct spdk_nvme_transport_id *trid,
1041 : const struct spdk_nvme_ctrlr_opts *opts,
1042 : spdk_nvme_attach_cb attach_cb);
1043 :
1044 : /**
1045 : * Probe and add controllers to the probe context list.
1046 : *
1047 : * Users must call spdk_nvme_probe_poll_async() to initialize
1048 : * controllers in the probe context list to the READY state.
1049 : *
1050 : * \param trid The transport ID indicating which bus to enumerate. If the trtype
1051 : * is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is
1052 : * fabrics (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an
1053 : * NVMe-oF discovery service.
1054 : * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of
1055 : * the callbacks.
1056 : * \param probe_cb will be called once per NVMe device found in the system.
1057 : * \param attach_cb will be called for devices for which probe_cb returned true
1058 : * once that NVMe controller has been attached to the userspace driver.
1059 : * \param remove_cb will be called for devices that were attached in a previous
1060 : * spdk_nvme_probe() call but are no longer attached to the system. Optional;
1061 : * specify NULL if removal notices are not desired.
1062 : *
1063 : * \return probe context on success, NULL on failure.
1064 : */
1065 : struct spdk_nvme_probe_ctx *spdk_nvme_probe_async(const struct spdk_nvme_transport_id *trid,
1066 : void *cb_ctx,
1067 : spdk_nvme_probe_cb probe_cb,
1068 : spdk_nvme_attach_cb attach_cb,
1069 : spdk_nvme_remove_cb remove_cb);
1070 :
1071 : /**
1072 : * Probe and add controllers to the probe context list.
1073 : *
1074 : * Users must call spdk_nvme_probe_poll_async() to initialize
1075 : * controllers in the probe context list to the READY state.
1076 : *
1077 : * This works just the same as spdk_nvme_probe_async(), except that it calls
1078 : * attach_fail_cb for devices that are probed but unabled to attach.
1079 : *
1080 : * \param trid The transport ID indicating which bus to enumerate. If the trtype
1081 : * is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is
1082 : * fabrics (e.g. RDMA, TCP), the traddr and trsvcid must point at the location of an
1083 : * NVMe-oF discovery service.
1084 : * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of
1085 : * the callbacks.
1086 : * \param probe_cb will be called once per NVMe device found in the system.
1087 : * \param attach_cb will be called for devices for which probe_cb returned true
1088 : * once that NVMe controller has been attached to the userspace driver.
1089 : * \param attach_fail_cb will be called for devices which probe_cb returned true
1090 : * but failed to attach to the userspace driver.
1091 : * \param remove_cb will be called for devices that were attached in a previous
1092 : * spdk_nvme_probe() call but are no longer attached to the system. Optional;
1093 : * specify NULL if removal notices are not desired.
1094 : *
1095 : * \return probe context on success, NULL on failure.
1096 : */
1097 : struct spdk_nvme_probe_ctx *spdk_nvme_probe_async_ext(const struct spdk_nvme_transport_id *trid,
1098 : void *cb_ctx,
1099 : spdk_nvme_probe_cb probe_cb,
1100 : spdk_nvme_attach_cb attach_cb,
1101 : spdk_nvme_attach_fail_cb attach_fail_cb,
1102 : spdk_nvme_remove_cb remove_cb);
1103 :
1104 : /**
1105 : * Proceed with attaching controllers associated with the probe context.
1106 : *
1107 : * The probe context is one returned from a previous call to
1108 : * spdk_nvme_probe_async(). Users must call this function on the
1109 : * probe context until it returns 0.
1110 : *
1111 : * If any controllers fail to attach, there is no explicit notification.
1112 : * Users can detect attachment failure by comparing attach_cb invocations
1113 : * with the number of times where the user returned true for the
1114 : * probe_cb.
1115 : *
1116 : * \param probe_ctx Context used to track probe actions.
1117 : *
1118 : * \return 0 if all probe operations are complete; the probe_ctx
1119 : * is also freed and no longer valid.
1120 : * \return -EAGAIN if there are still pending probe operations; user must call
1121 : * spdk_nvme_probe_poll_async again to continue progress.
1122 : */
1123 : int spdk_nvme_probe_poll_async(struct spdk_nvme_probe_ctx *probe_ctx);
1124 :
1125 : /**
1126 : * Detach specified device returned by spdk_nvme_probe()'s attach_cb from the
1127 : * NVMe driver.
1128 : *
1129 : * On success, the spdk_nvme_ctrlr handle is no longer valid.
1130 : *
1131 : * This function should be called from a single thread while no other threads
1132 : * are actively using the NVMe device.
1133 : *
1134 : * \param ctrlr Opaque handle to NVMe controller.
1135 : *
1136 : * \return 0 on success, -1 on failure.
1137 : */
1138 : int spdk_nvme_detach(struct spdk_nvme_ctrlr *ctrlr);
1139 :
1140 : struct spdk_nvme_detach_ctx;
1141 :
1142 : /**
1143 : * Allocate a context to track detachment of multiple controllers if this call is the
1144 : * first successful start of detachment in a sequence, or use the passed context otherwise.
1145 : *
1146 : * Then, start detaching the specified device returned by spdk_nvme_probe()'s attach_cb
1147 : * from the NVMe driver, and append this detachment to the context.
1148 : *
1149 : * User must call spdk_nvme_detach_poll_async() to complete the detachment.
1150 : *
1151 : * If the context is not allocated before this call, and if the specified device is detached
1152 : * locally from the caller process but any other process still attaches it or failed to be
1153 : * detached, context is not allocated.
1154 : *
1155 : * This function should be called from a single thread while no other threads are
1156 : * actively using the NVMe device.
1157 : *
1158 : * \param ctrlr Opaque handle to NVMe controller.
1159 : * \param detach_ctx Reference to the context in a sequence. An new context is allocated
1160 : * if this call is the first successful start of detachment in a sequence, or use the
1161 : * passed context.
1162 : */
1163 : int spdk_nvme_detach_async(struct spdk_nvme_ctrlr *ctrlr,
1164 : struct spdk_nvme_detach_ctx **detach_ctx);
1165 :
1166 : /**
1167 : * Poll detachment of multiple controllers until they complete.
1168 : *
1169 : * User must call this function until it returns 0.
1170 : *
1171 : * \param detach_ctx Context to track the detachment.
1172 : *
1173 : * \return 0 if all detachments complete; the context is also freed and no longer valid.
1174 : * \return -EAGAIN if any detachment is still in progress; users must call
1175 : * spdk_nvme_detach_poll_async() again to continue progress.
1176 : */
1177 : int spdk_nvme_detach_poll_async(struct spdk_nvme_detach_ctx *detach_ctx);
1178 :
1179 : /**
1180 : * Continue calling spdk_nvme_detach_poll_async() internally until it returns 0.
1181 : *
1182 : * \param detach_ctx Context to track the detachment.
1183 : */
1184 : void spdk_nvme_detach_poll(struct spdk_nvme_detach_ctx *detach_ctx);
1185 :
1186 : /**
1187 : * Scan attached controllers for events.
1188 : *
1189 : * This function lets user act on events such as hot-remove without a need to
1190 : * enable hotplug explicitly. Only attached devices will be checked.
1191 : *
1192 : * \param trid Transport ID.
1193 : *
1194 : * \returns 0 on success, negative on failure.
1195 : */
1196 : int spdk_nvme_scan_attached(const struct spdk_nvme_transport_id *trid);
1197 :
1198 : /**
1199 : * Update the transport ID for a given controller.
1200 : *
1201 : * This function allows the user to set a new trid for a controller only if the
1202 : * controller is failed. The controller's failed state can be obtained from
1203 : * spdk_nvme_ctrlr_is_failed(). The controller can also be forced to the failed
1204 : * state using spdk_nvme_ctrlr_fail().
1205 : *
1206 : * This function also requires that the transport type and subnqn of the new trid
1207 : * be the same as the old trid.
1208 : *
1209 : * \param ctrlr Opaque handle to an NVMe controller.
1210 : * \param trid The new transport ID.
1211 : *
1212 : * \return 0 on success, -EINVAL if the trid is invalid,
1213 : * -EPERM if the ctrlr is not failed.
1214 : */
1215 : int spdk_nvme_ctrlr_set_trid(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_transport_id *trid);
1216 :
1217 : /**
1218 : * Set the remove callback and context to be invoked if the controller is removed.
1219 : *
1220 : * This will override any remove_cb and/or ctx specified when the controller was
1221 : * probed.
1222 : *
1223 : * This function may only be called from the primary process. This function has
1224 : * no effect if called from a secondary process.
1225 : *
1226 : * \param ctrlr Opaque handle to an NVMe controller.
1227 : * \param remove_cb remove callback
1228 : * \param remove_ctx remove callback context
1229 : */
1230 : void spdk_nvme_ctrlr_set_remove_cb(struct spdk_nvme_ctrlr *ctrlr,
1231 : spdk_nvme_remove_cb remove_cb, void *remove_ctx);
1232 :
1233 : struct spdk_nvme_ctrlr_key_opts {
1234 : /** Size of this structure */
1235 : size_t size;
1236 : /** DH-HMAC-CHAP host key */
1237 : struct spdk_key *dhchap_key;
1238 : /** DH-HMAC-CHAP controller key */
1239 : struct spdk_key *dhchap_ctrlr_key;
1240 : };
1241 :
1242 : /**
1243 : * Set keys for a given NVMe controller. These keys will override the keys specified in
1244 : * `spdk_nvme_ctrlr_opts` when attaching the controller and will be used from now on to authenticate
1245 : * all qpairs associated with this controller.
1246 : *
1247 : * This function only sets the keys, it doesn't force existing qpairs to use them. To do that,
1248 : * users need to call `spdk_nvme_ctrlr_authenticate()` to authenticate the admin queue and
1249 : * `spdk_nvme_qpair_authenticate()` to authenticate IO queues.
1250 : *
1251 : * \param ctrlr NVMe controller.
1252 : * \param opts Key options.
1253 : *
1254 : * \return 0 on success, negative errno on failure.
1255 : */
1256 : int spdk_nvme_ctrlr_set_keys(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_ctrlr_key_opts *opts);
1257 :
1258 : /**
1259 : * Perform a full hardware reset of the NVMe controller.
1260 : *
1261 : * This function should be called from a single thread while no other threads
1262 : * are actively using the NVMe device.
1263 : *
1264 : * Any pointers returned from spdk_nvme_ctrlr_get_ns(), spdk_nvme_ns_get_data(),
1265 : * spdk_nvme_zns_ns_get_data(), and spdk_nvme_zns_ctrlr_get_data()
1266 : * may be invalidated by calling this function. The number of namespaces as returned
1267 : * by spdk_nvme_ctrlr_get_num_ns() may also change.
1268 : *
1269 : * \param ctrlr Opaque handle to NVMe controller.
1270 : *
1271 : * \return 0 on success, -1 on failure.
1272 : */
1273 : int spdk_nvme_ctrlr_reset(struct spdk_nvme_ctrlr *ctrlr);
1274 :
1275 : /**
1276 : * Disconnect the given NVMe controller.
1277 : *
1278 : * This function is used as the first operation of a full reset sequence of the given NVMe
1279 : * controller. The NVMe controller is ready to reconnect after completing this function.
1280 : *
1281 : * \param ctrlr Opaque handle to NVMe controller.
1282 : *
1283 : * \return 0 on success, -EBUSY if controller is already resetting, or -ENXIO if controller
1284 : * has been removed.
1285 : */
1286 : int spdk_nvme_ctrlr_disconnect(struct spdk_nvme_ctrlr *ctrlr);
1287 :
1288 : /**
1289 : * Start re-enabling the given NVMe controller in a full reset sequence
1290 : *
1291 : * \param ctrlr Opaque handle to NVMe controller.
1292 : */
1293 : void spdk_nvme_ctrlr_reconnect_async(struct spdk_nvme_ctrlr *ctrlr);
1294 :
1295 : /**
1296 : * Proceed with re-enabling the given NVMe controller.
1297 : *
1298 : * Users must call this function in a full reset sequence until it returns a value other
1299 : * than -EAGAIN.
1300 : *
1301 : * \return 0 if the given NVMe controller is enabled, or -EBUSY if there are still
1302 : * pending operations to enable it.
1303 : */
1304 : int spdk_nvme_ctrlr_reconnect_poll_async(struct spdk_nvme_ctrlr *ctrlr);
1305 :
1306 : /**
1307 : * Perform a NVMe subsystem reset.
1308 : *
1309 : * This function should be called from a single thread while no other threads
1310 : * are actively using the NVMe device.
1311 : * A subsystem reset is typically seen by the OS as a hot remove, followed by a
1312 : * hot add event.
1313 : *
1314 : * Any pointers returned from spdk_nvme_ctrlr_get_ns(), spdk_nvme_ns_get_data(),
1315 : * spdk_nvme_zns_ns_get_data(), and spdk_nvme_zns_ctrlr_get_data()
1316 : * may be invalidated by calling this function. The number of namespaces as returned
1317 : * by spdk_nvme_ctrlr_get_num_ns() may also change.
1318 : *
1319 : * \param ctrlr Opaque handle to NVMe controller.
1320 : *
1321 : * \return 0 on success, -1 on failure, -ENOTSUP if subsystem reset is not supported.
1322 : */
1323 : int spdk_nvme_ctrlr_reset_subsystem(struct spdk_nvme_ctrlr *ctrlr);
1324 :
1325 : /**
1326 : * Fail the given NVMe controller.
1327 : *
1328 : * This function gives the application the opportunity to fail a controller
1329 : * at will. When a controller is failed, any calls to process completions or
1330 : * submit I/O on qpairs associated with that controller will fail with an error
1331 : * code of -ENXIO.
1332 : * The controller can only be taken from the failed state by
1333 : * calling spdk_nvme_ctrlr_reset. After the controller has been successfully
1334 : * reset, any I/O pending when the controller was moved to failed will be
1335 : * aborted back to the application and can be resubmitted. I/O can then resume.
1336 : *
1337 : * \param ctrlr Opaque handle to an NVMe controller.
1338 : */
1339 : void spdk_nvme_ctrlr_fail(struct spdk_nvme_ctrlr *ctrlr);
1340 :
1341 : /**
1342 : * This function returns the failed status of a given controller.
1343 : *
1344 : * \param ctrlr Opaque handle to an NVMe controller.
1345 : *
1346 : * \return True if the controller is failed, false otherwise.
1347 : */
1348 : bool spdk_nvme_ctrlr_is_failed(struct spdk_nvme_ctrlr *ctrlr);
1349 :
1350 : /**
1351 : * Get the identify controller data as defined by the NVMe specification.
1352 : *
1353 : * This function is thread safe and can be called at any point while the controller
1354 : * is attached to the SPDK NVMe driver.
1355 : *
1356 : * \param ctrlr Opaque handle to NVMe controller.
1357 : *
1358 : * \return pointer to the identify controller data.
1359 : */
1360 : const struct spdk_nvme_ctrlr_data *spdk_nvme_ctrlr_get_data(struct spdk_nvme_ctrlr *ctrlr);
1361 :
1362 : /**
1363 : * Get the NVMe controller CSTS (Status) register.
1364 : *
1365 : * \param ctrlr Opaque handle to NVMe controller.
1366 : *
1367 : * \return the NVMe controller CSTS (Status) register.
1368 : */
1369 : union spdk_nvme_csts_register spdk_nvme_ctrlr_get_regs_csts(struct spdk_nvme_ctrlr *ctrlr);
1370 :
1371 : /**
1372 : * Get the NVMe controller CC (Configuration) register.
1373 : *
1374 : * \param ctrlr Opaque handle to NVMe controller.
1375 : *
1376 : * \return the NVMe controller CC (Configuration) register.
1377 : */
1378 : union spdk_nvme_cc_register spdk_nvme_ctrlr_get_regs_cc(struct spdk_nvme_ctrlr *ctrlr);
1379 :
1380 : /**
1381 : * Get the NVMe controller CAP (Capabilities) register.
1382 : *
1383 : * \param ctrlr Opaque handle to NVMe controller.
1384 : *
1385 : * \return the NVMe controller CAP (Capabilities) register.
1386 : */
1387 : union spdk_nvme_cap_register spdk_nvme_ctrlr_get_regs_cap(struct spdk_nvme_ctrlr *ctrlr);
1388 :
1389 : /**
1390 : * Get the NVMe controller VS (Version) register.
1391 : *
1392 : * \param ctrlr Opaque handle to NVMe controller.
1393 : *
1394 : * \return the NVMe controller VS (Version) register.
1395 : */
1396 : union spdk_nvme_vs_register spdk_nvme_ctrlr_get_regs_vs(struct spdk_nvme_ctrlr *ctrlr);
1397 :
1398 : /**
1399 : * Get the NVMe controller CMBSZ (Controller Memory Buffer Size) register
1400 : *
1401 : * \param ctrlr Opaque handle to NVMe controller.
1402 : *
1403 : * \return the NVMe controller CMBSZ (Controller Memory Buffer Size) register.
1404 : */
1405 : union spdk_nvme_cmbsz_register spdk_nvme_ctrlr_get_regs_cmbsz(struct spdk_nvme_ctrlr *ctrlr);
1406 :
1407 : /**
1408 : * Get the NVMe controller PMRCAP (Persistent Memory Region Capabilities) register.
1409 : *
1410 : * \param ctrlr Opaque handle to NVMe controller.
1411 : *
1412 : * \return the NVMe controller PMRCAP (Persistent Memory Region Capabilities) register.
1413 : */
1414 : union spdk_nvme_pmrcap_register spdk_nvme_ctrlr_get_regs_pmrcap(struct spdk_nvme_ctrlr *ctrlr);
1415 :
1416 : /**
1417 : * Get the NVMe controller BPINFO (Boot Partition Information) register.
1418 : *
1419 : * \param ctrlr Opaque handle to NVMe controller.
1420 : *
1421 : * \return the NVMe controller BPINFO (Boot Partition Information) register.
1422 : */
1423 : union spdk_nvme_bpinfo_register spdk_nvme_ctrlr_get_regs_bpinfo(struct spdk_nvme_ctrlr *ctrlr);
1424 :
1425 : /**
1426 : * Get the NVMe controller PMR size.
1427 : *
1428 : * \param ctrlr Opaque handle to NVMe controller.
1429 : *
1430 : * \return the NVMe controller PMR size or 0 if PMR is not supported.
1431 : */
1432 : uint64_t spdk_nvme_ctrlr_get_pmrsz(struct spdk_nvme_ctrlr *ctrlr);
1433 :
1434 : /**
1435 : * Get the maximum NSID value that will ever be used for the given controller
1436 : *
1437 : * This function is thread safe and can be called at any point while the
1438 : * controller is attached to the SPDK NVMe driver.
1439 : *
1440 : * This is equivalent to calling spdk_nvme_ctrlr_get_data() to get the
1441 : * spdk_nvme_ctrlr_data and then reading the nn field.
1442 : *
1443 : * The NN field in the NVMe specification represents the maximum value that a
1444 : * namespace ID can ever have. Prior to NVMe 1.2, this was also the number of
1445 : * active namespaces, but from 1.2 onward the list of namespaces may be
1446 : * sparsely populated. Unfortunately, the meaning of this field is often
1447 : * misinterpreted by drive manufacturers and NVMe-oF implementers so it is
1448 : * not considered reliable. AVOID USING THIS FUNCTION WHENEVER POSSIBLE.
1449 : *
1450 : * \param ctrlr Opaque handle to NVMe controller.
1451 : *
1452 : * \return the number of namespaces.
1453 : */
1454 : uint32_t spdk_nvme_ctrlr_get_num_ns(struct spdk_nvme_ctrlr *ctrlr);
1455 :
1456 : /**
1457 : * Get the PCI device of a given NVMe controller.
1458 : *
1459 : * This only works for local (PCIe-attached) NVMe controllers; other transports
1460 : * will return NULL.
1461 : *
1462 : * \param ctrlr Opaque handle to NVMe controller.
1463 : *
1464 : * \return PCI device of the NVMe controller, or NULL if not available.
1465 : */
1466 : struct spdk_pci_device *spdk_nvme_ctrlr_get_pci_device(struct spdk_nvme_ctrlr *ctrlr);
1467 :
1468 : /**
1469 : * Get the NUMA ID for the given NVMe controller.
1470 : *
1471 : * For network-based transports, the NUMA ID will be correlated to the
1472 : * network interface.
1473 : *
1474 : * \param ctrlr Opaque handle to NVMe controller
1475 : *
1476 : * \return NUMA ID of the NVMe controller, or SPDK_ENV_NUMA_ID_ANY if
1477 : * the NUMA ID is unknown
1478 : */
1479 : int32_t spdk_nvme_ctrlr_get_numa_id(struct spdk_nvme_ctrlr *ctrlr);
1480 :
1481 : /**
1482 : * Get the NVMe controller ID for the given controller.
1483 : *
1484 : * \param ctrlr Opaque handle to NVMe controller.
1485 : *
1486 : * \return ID of the NVMe controller.
1487 : */
1488 : uint16_t spdk_nvme_ctrlr_get_id(struct spdk_nvme_ctrlr *ctrlr);
1489 :
1490 : /**
1491 : * Get the maximum data transfer size of a given NVMe controller.
1492 : *
1493 : * \param ctrlr Opaque handle to NVMe controller.
1494 : *
1495 : * \return Maximum data transfer size of the NVMe controller in bytes.
1496 : *
1497 : * The I/O command helper functions, such as spdk_nvme_ns_cmd_read(), will split
1498 : * large I/Os automatically; however, it is up to the user to obey this limit for
1499 : * commands submitted with the raw command functions, such as spdk_nvme_ctrlr_cmd_io_raw().
1500 : */
1501 : uint32_t spdk_nvme_ctrlr_get_max_xfer_size(const struct spdk_nvme_ctrlr *ctrlr);
1502 :
1503 : /**
1504 : * Get the maximum number of SGEs per request for the given NVMe controller.
1505 : *
1506 : * Controllers that do not support SGL will return UINT16_MAX.
1507 : *
1508 : * \param ctrlr Opaque handle to NVMe controller.
1509 : *
1510 : * \return Maximum number of SGEs per request
1511 : */
1512 : uint16_t spdk_nvme_ctrlr_get_max_sges(const struct spdk_nvme_ctrlr *ctrlr);
1513 :
1514 : /**
1515 : * Check whether the nsid is an active nv for the given NVMe controller.
1516 : *
1517 : * This function is thread safe and can be called at any point while the controller
1518 : * is attached to the SPDK NVMe driver.
1519 : *
1520 : * \param ctrlr Opaque handle to NVMe controller.
1521 : * \param nsid Namespace id.
1522 : *
1523 : * \return true if nsid is an active ns, or false otherwise.
1524 : */
1525 : bool spdk_nvme_ctrlr_is_active_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid);
1526 :
1527 : /**
1528 : * Get the nsid of the first active namespace.
1529 : *
1530 : * This function is thread safe and can be called at any point while the controller
1531 : * is attached to the SPDK NVMe driver.
1532 : *
1533 : * \param ctrlr Opaque handle to NVMe controller.
1534 : *
1535 : * \return the nsid of the first active namespace, 0 if there are no active namespaces.
1536 : */
1537 : uint32_t spdk_nvme_ctrlr_get_first_active_ns(struct spdk_nvme_ctrlr *ctrlr);
1538 :
1539 : /**
1540 : * Get next active namespace given the previous nsid.
1541 : *
1542 : * This function is thread safe and can be called at any point while the controller
1543 : * is attached to the SPDK NVMe driver.
1544 : *
1545 : * \param ctrlr Opaque handle to NVMe controller.
1546 : * \param prev_nsid Namespace id.
1547 : *
1548 : * \return a next active namespace given the previous nsid, 0 when there are no
1549 : * more active namespaces.
1550 : */
1551 : uint32_t spdk_nvme_ctrlr_get_next_active_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t prev_nsid);
1552 :
1553 : /**
1554 : * Determine if a particular log page is supported by the given NVMe controller.
1555 : *
1556 : * This function is thread safe and can be called at any point while the controller
1557 : * is attached to the SPDK NVMe driver.
1558 : *
1559 : * \sa spdk_nvme_ctrlr_cmd_get_log_page().
1560 : *
1561 : * \param ctrlr Opaque handle to NVMe controller.
1562 : * \param log_page Log page to query.
1563 : *
1564 : * \return true if supported, or false otherwise.
1565 : */
1566 : bool spdk_nvme_ctrlr_is_log_page_supported(struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page);
1567 :
1568 : /**
1569 : * Determine if a particular feature is supported by the given NVMe controller.
1570 : *
1571 : * This function is thread safe and can be called at any point while the controller
1572 : * is attached to the SPDK NVMe driver.
1573 : *
1574 : * \sa spdk_nvme_ctrlr_cmd_get_feature().
1575 : *
1576 : * \param ctrlr Opaque handle to NVMe controller.
1577 : * \param feature_code Feature to query.
1578 : *
1579 : * \return true if supported, or false otherwise.
1580 : */
1581 : bool spdk_nvme_ctrlr_is_feature_supported(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature_code);
1582 :
1583 : /**
1584 : * Signature for callback function invoked when a command is completed.
1585 : *
1586 : * \param ctx Callback context provided when the command was submitted.
1587 : * \param cpl Completion queue entry that contains the completion status.
1588 : */
1589 : typedef void (*spdk_nvme_cmd_cb)(void *ctx, const struct spdk_nvme_cpl *cpl);
1590 :
1591 : /**
1592 : * Signature for callback function invoked when an asynchronous event request
1593 : * command is completed.
1594 : *
1595 : * \param aer_cb_arg Context specified by spdk_nvme_register_aer_callback().
1596 : * \param cpl Completion queue entry that contains the completion status
1597 : * of the asynchronous event request that was completed.
1598 : */
1599 : typedef void (*spdk_nvme_aer_cb)(void *aer_cb_arg,
1600 : const struct spdk_nvme_cpl *cpl);
1601 :
1602 : /**
1603 : * Register callback function invoked when an AER command is completed for the
1604 : * given NVMe controller.
1605 : *
1606 : * \param ctrlr Opaque handle to NVMe controller.
1607 : * \param aer_cb_fn Callback function invoked when an asynchronous event request
1608 : * command is completed.
1609 : * \param aer_cb_arg Argument passed to callback function.
1610 : */
1611 : void spdk_nvme_ctrlr_register_aer_callback(struct spdk_nvme_ctrlr *ctrlr,
1612 : spdk_nvme_aer_cb aer_cb_fn,
1613 : void *aer_cb_arg);
1614 :
1615 : /**
1616 : * Disable reading the CHANGED_NS_LIST log page for the specified controller.
1617 : *
1618 : * Applications that register an AER callback may wish to read the CHANGED_NS_LIST
1619 : * log page itself, rather than relying on the driver to do it. Calling this
1620 : * function will ensure that the driver does not read this log page if the
1621 : * controller returns a NS_ATTR_CHANGED AEN.
1622 : *
1623 : * Reading of this log page can alternatively be disabled by setting the
1624 : * disable_read_changed_ns_list_log_page flag in the spdk_nvme_ctrlr_opts
1625 : * when attaching the controller.
1626 : *
1627 : * \param ctrlr NVMe controller on which to disable the log page read.
1628 : */
1629 : void spdk_nvme_ctrlr_disable_read_changed_ns_list_log_page(struct spdk_nvme_ctrlr *ctrlr);
1630 :
1631 : /**
1632 : * Opaque handle to a queue pair.
1633 : *
1634 : * I/O queue pairs may be allocated using spdk_nvme_ctrlr_alloc_io_qpair().
1635 : */
1636 : struct spdk_nvme_qpair;
1637 :
1638 : /**
1639 : * Signature for the callback function invoked when a timeout is detected on a
1640 : * request.
1641 : *
1642 : * For timeouts detected on the admin queue pair, the qpair returned here will
1643 : * be NULL. If the controller has a serious error condition and is unable to
1644 : * communicate with driver via completion queue, the controller can set Controller
1645 : * Fatal Status field to 1, then reset is required to recover from such error.
1646 : * Users may detect Controller Fatal Status when timeout happens.
1647 : *
1648 : * \param cb_arg Argument passed to callback function.
1649 : * \param ctrlr Opaque handle to NVMe controller.
1650 : * \param qpair Opaque handle to a queue pair.
1651 : * \param cid Command ID.
1652 : */
1653 : typedef void (*spdk_nvme_timeout_cb)(void *cb_arg,
1654 : struct spdk_nvme_ctrlr *ctrlr,
1655 : struct spdk_nvme_qpair *qpair,
1656 : uint16_t cid);
1657 :
1658 : /**
1659 : * Register for timeout callback on a controller.
1660 : *
1661 : * The application can choose to register for timeout callback or not register
1662 : * for timeout callback.
1663 : *
1664 : * \param ctrlr NVMe controller on which to monitor for timeout.
1665 : * \param timeout_io_us Timeout value in microseconds for io commands.
1666 : * \param timeout_admin_us Timeout value in microseconds for admin commands.
1667 : * \param cb_fn A function pointer that points to the callback function.
1668 : * \param cb_arg Argument to the callback function.
1669 : */
1670 : void spdk_nvme_ctrlr_register_timeout_callback(struct spdk_nvme_ctrlr *ctrlr,
1671 : uint64_t timeout_io_us, uint64_t timeout_admin_us,
1672 : spdk_nvme_timeout_cb cb_fn, void *cb_arg);
1673 :
1674 : /**
1675 : * Signature for the callback function when a
1676 : * \ref spdk_nvme_ctrlr_get_discovery_log_page operation is completed.
1677 : *
1678 : * \param cb_arg Argument passed to callback function.
1679 : * \param rc Status of operation. 0 means success, and that the cpl argument is valid.
1680 : * Failure indicated by negative errno value.
1681 : * \param cpl NVMe completion status of the operation. NULL if rc != 0. If multiple
1682 : * completions with error status occurred during the operation, the cpl
1683 : * value for the first error will be used here.
1684 : * \param log_page Pointer to the full discovery log page. The application is
1685 : * responsible for freeing this buffer using free().
1686 : */
1687 : typedef void (*spdk_nvme_discovery_cb)(void *cb_arg, int rc,
1688 : const struct spdk_nvme_cpl *cpl,
1689 : struct spdk_nvmf_discovery_log_page *log_page);
1690 :
1691 : /**
1692 : * Get a full discovery log page from the specified controller.
1693 : *
1694 : * This function will first read the discovery log header to determine the
1695 : * total number of valid entries in the discovery log, then it will allocate
1696 : * a buffer to hold the entire log and issue multiple GET_LOG_PAGE commands to
1697 : * get all of the entries.
1698 : *
1699 : * The application is responsible for calling
1700 : * \ref spdk_nvme_ctrlr_process_admin_completions to trigger processing of
1701 : * completions submitted by this function.
1702 : *
1703 : * \param ctrlr Pointer to the discovery controller.
1704 : * \param cb_fn Function to call when the operation is complete.
1705 : * \param cb_arg Argument to pass to cb_fn.
1706 : */
1707 : int spdk_nvme_ctrlr_get_discovery_log_page(struct spdk_nvme_ctrlr *ctrlr,
1708 : spdk_nvme_discovery_cb cb_fn, void *cb_arg);
1709 :
1710 : /**
1711 : * NVMe I/O queue pair initialization options.
1712 : *
1713 : * These options may be passed to spdk_nvme_ctrlr_alloc_io_qpair() to configure queue pair
1714 : * options at queue creation time.
1715 : *
1716 : * The user may retrieve the default I/O queue pair creation options for a controller using
1717 : * spdk_nvme_ctrlr_get_default_io_qpair_opts().
1718 : */
1719 : struct spdk_nvme_io_qpair_opts {
1720 : /**
1721 : * Queue priority for weighted round robin arbitration. If a different arbitration
1722 : * method is in use, pass 0.
1723 : */
1724 : enum spdk_nvme_qprio qprio;
1725 :
1726 : /**
1727 : * The queue depth of this NVMe I/O queue. Overrides spdk_nvme_ctrlr_opts::io_queue_size.
1728 : */
1729 : uint32_t io_queue_size;
1730 :
1731 : /**
1732 : * The number of requests to allocate for this NVMe I/O queue.
1733 : *
1734 : * Overrides spdk_nvme_ctrlr_opts::io_queue_requests.
1735 : *
1736 : * This should be at least as large as io_queue_size.
1737 : *
1738 : * A single I/O may allocate more than one request, since splitting may be
1739 : * necessary to conform to the device's maximum transfer size, PRP list
1740 : * compatibility requirements, or driver-assisted striping.
1741 : */
1742 : uint32_t io_queue_requests;
1743 :
1744 : /**
1745 : * When submitting I/O via spdk_nvme_ns_read/write and similar functions,
1746 : * don't immediately submit it to hardware. Instead, queue up new commands
1747 : * and submit them to the hardware inside spdk_nvme_qpair_process_completions().
1748 : *
1749 : * This results in better batching of I/O commands. Often, it is more efficient
1750 : * to submit batches of commands to the underlying hardware than each command
1751 : * individually.
1752 : *
1753 : * This only applies to PCIe and RDMA transports.
1754 : *
1755 : * The flag was originally named delay_pcie_doorbell. To allow backward compatibility
1756 : * both names are kept in unnamed union.
1757 : */
1758 : union {
1759 : bool delay_cmd_submit;
1760 : bool delay_pcie_doorbell;
1761 : };
1762 :
1763 : /* Hole at bytes 13-15. */
1764 : uint8_t reserved13[3];
1765 :
1766 : /**
1767 : * These fields allow specifying the memory buffers for the submission and/or
1768 : * completion queues.
1769 : * By default, vaddr is set to NULL meaning SPDK will allocate the memory to be used.
1770 : * If vaddr is NULL then paddr must be set to 0.
1771 : * If vaddr is non-NULL, and paddr is zero, SPDK derives the physical
1772 : * address for the NVMe device, in this case the memory must be registered.
1773 : * If a paddr value is non-zero, SPDK uses the vaddr and paddr as passed
1774 : * SPDK assumes that the memory passed is both virtually and physically
1775 : * contiguous.
1776 : * If these fields are used, SPDK will NOT impose any restriction
1777 : * on the number of elements in the queues.
1778 : * The buffer sizes are in number of bytes, and are used to confirm
1779 : * that the buffers are large enough to contain the appropriate queue.
1780 : * These fields are only used by PCIe attached NVMe devices. They
1781 : * are presently ignored for other transports.
1782 : */
1783 : struct {
1784 : struct spdk_nvme_cmd *vaddr;
1785 : uint64_t paddr;
1786 : uint64_t buffer_size;
1787 : } sq;
1788 : struct {
1789 : struct spdk_nvme_cpl *vaddr;
1790 : uint64_t paddr;
1791 : uint64_t buffer_size;
1792 : } cq;
1793 :
1794 : /**
1795 : * This flag indicates to the alloc_io_qpair function that it should not perform
1796 : * the connect portion on this qpair. This allows the user to add the qpair to a
1797 : * poll group and then connect it later.
1798 : */
1799 : bool create_only;
1800 :
1801 : /**
1802 : * This flag if set to true enables the creation of submission and completion queue
1803 : * asynchronously. Default mode is set to false to create io qpair synchronously.
1804 : */
1805 : bool async_mode;
1806 :
1807 : /**
1808 : * This flag if set to true disables the merging of physically
1809 : * contiguous SGL elements. Default mode is set to false to allow
1810 : * merging of physically contiguous SGL elements.
1811 : */
1812 : bool disable_pcie_sgl_merge;
1813 :
1814 : /* Hole at bytes 67-71. */
1815 : uint8_t reserved67[5];
1816 :
1817 : /**
1818 : * The size of spdk_nvme_io_qpair_opts according to the caller of this library is used for
1819 : * ABI compatibility. The library uses this field to know how many fields in this structure
1820 : * are valid. And the library will populate any remaining fields with default values.
1821 : * New added fields should be put at the end of the struct.
1822 : */
1823 : size_t opts_size;
1824 : };
1825 : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_io_qpair_opts) == 80, "Incorrect size");
1826 :
1827 : /**
1828 : * Get the default options for I/O qpair creation for a specific NVMe controller.
1829 : *
1830 : * \param ctrlr NVMe controller to retrieve the defaults from.
1831 : * \param[out] opts Will be filled with the default options for
1832 : * spdk_nvme_ctrlr_alloc_io_qpair().
1833 : * \param opts_size Must be set to sizeof(struct spdk_nvme_io_qpair_opts).
1834 : */
1835 : void spdk_nvme_ctrlr_get_default_io_qpair_opts(struct spdk_nvme_ctrlr *ctrlr,
1836 : struct spdk_nvme_io_qpair_opts *opts,
1837 : size_t opts_size);
1838 :
1839 : /**
1840 : * Allocate an I/O queue pair (submission and completion queue).
1841 : *
1842 : * This function by default also performs any connection activities required for
1843 : * a newly created qpair. To avoid that behavior, the user should set the create_only
1844 : * flag in the opts structure to true.
1845 : *
1846 : * Each queue pair should only be used from a single thread at a time (mutual
1847 : * exclusion must be enforced by the user).
1848 : *
1849 : * \param ctrlr NVMe controller for which to allocate the I/O queue pair.
1850 : * \param opts I/O qpair creation options, or NULL to use the defaults as returned
1851 : * by spdk_nvme_ctrlr_get_default_io_qpair_opts().
1852 : * \param opts_size Must be set to sizeof(struct spdk_nvme_io_qpair_opts), or 0
1853 : * if opts is NULL.
1854 : *
1855 : * \return a pointer to the allocated I/O queue pair.
1856 : */
1857 : struct spdk_nvme_qpair *spdk_nvme_ctrlr_alloc_io_qpair(struct spdk_nvme_ctrlr *ctrlr,
1858 : const struct spdk_nvme_io_qpair_opts *opts,
1859 : size_t opts_size);
1860 :
1861 : /**
1862 : * Connect a newly created I/O qpair.
1863 : *
1864 : * This function does any connection activities required for a newly created qpair.
1865 : * It should be called after spdk_nvme_ctrlr_alloc_io_qpair has been called with the
1866 : * create_only flag set to true in the spdk_nvme_io_qpair_opts structure.
1867 : *
1868 : * This call will fail if performed on a qpair that is already connected.
1869 : * For reconnecting qpairs, see spdk_nvme_ctrlr_reconnect_io_qpair.
1870 : *
1871 : * For fabrics like TCP and RDMA, this function actually sends the commands over the wire
1872 : * that connect the qpair. For PCIe, this function performs some internal state machine operations.
1873 : *
1874 : * \param ctrlr NVMe controller for which to allocate the I/O queue pair.
1875 : * \param qpair Opaque handle to the qpair to connect.
1876 : *
1877 : * return 0 on success or negated errno on failure. Specifically -EISCONN if the qpair is already connected.
1878 : *
1879 : */
1880 : int spdk_nvme_ctrlr_connect_io_qpair(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
1881 :
1882 : /**
1883 : * Disconnect the given I/O qpair.
1884 : *
1885 : * This function must be called from the same thread as spdk_nvme_qpair_process_completions
1886 : * and the spdk_nvme_ns_cmd_* functions.
1887 : *
1888 : * After disconnect, calling spdk_nvme_qpair_process_completions or one of the
1889 : * spdk_nvme_ns_cmd* on a qpair will result in a return value of -ENXIO. A
1890 : * disconnected qpair may be reconnected with either the spdk_nvme_ctrlr_connect_io_qpair
1891 : * or spdk_nvme_ctrlr_reconnect_io_qpair APIs.
1892 : *
1893 : * \param qpair The qpair to disconnect.
1894 : */
1895 : void spdk_nvme_ctrlr_disconnect_io_qpair(struct spdk_nvme_qpair *qpair);
1896 :
1897 : /**
1898 : * Attempt to reconnect the given qpair.
1899 : *
1900 : * This function is intended to be called on qpairs that have already been connected,
1901 : * but have since entered a failed state as indicated by a return value of -ENXIO from
1902 : * either spdk_nvme_qpair_process_completions or one of the spdk_nvme_ns_cmd_* functions.
1903 : * This function must be called from the same thread as spdk_nvme_qpair_process_completions
1904 : * and the spdk_nvme_ns_cmd_* functions.
1905 : *
1906 : * Calling this function has the same effect as calling spdk_nvme_ctrlr_disconnect_io_qpair
1907 : * followed by spdk_nvme_ctrlr_connect_io_qpair.
1908 : *
1909 : * This function may be called on newly created qpairs, but it does extra checks and attempts
1910 : * to disconnect the qpair before connecting it. The recommended API for newly created qpairs
1911 : * is spdk_nvme_ctrlr_connect_io_qpair.
1912 : *
1913 : * \param qpair The qpair to reconnect.
1914 : *
1915 : * \return 0 on success, or if the qpair was already connected.
1916 : * -EAGAIN if the driver was unable to reconnect during this call,
1917 : * but the controller is still connected and is either resetting or enabled.
1918 : * -ENODEV if the controller is removed. In this case, the controller cannot be recovered
1919 : * and the application will have to destroy it and the associated qpairs.
1920 : * -ENXIO if the controller is in a failed state but is not yet resetting. In this case,
1921 : * the application should call spdk_nvme_ctrlr_reset to reset the entire controller.
1922 : */
1923 : int spdk_nvme_ctrlr_reconnect_io_qpair(struct spdk_nvme_qpair *qpair);
1924 :
1925 : /**
1926 : * Opaque extended event handler options.
1927 : */
1928 : struct spdk_event_handler_opts;
1929 :
1930 : /**
1931 : * Get file descriptor for the admin queue pair of a controller.
1932 : *
1933 : * Applications that enable interrupts for completion notification will register and unregister
1934 : * interrupt event source on its queue pair file descriptor. This function returns file descriptor
1935 : * of the admin queue pair.
1936 : * This function also allows the transport layer to fill out event handler opts required by the
1937 : * application during interrupt registration phase.
1938 : *
1939 : * \param ctrlr Controller for which fd has to be fetched.
1940 : * \param[out] opts Event handler options to be filled by the transport, or NULL.
1941 : *
1942 : * \return a valid fd on success, with opts filled out if specified.
1943 : * -ENOTSUP if transport does not support fetching fd for this controller.
1944 : * -EINVAL if opts is specified, but its size is incorrect.
1945 : * -EINVAL if fds are not reserved, -1 if interrupts are not enabled for this controller.
1946 : */
1947 : int spdk_nvme_ctrlr_get_admin_qp_fd(struct spdk_nvme_ctrlr *ctrlr,
1948 : struct spdk_event_handler_opts *opts);
1949 :
1950 : /**
1951 : * Returns the reason the admin qpair for a given controller is disconnected.
1952 : *
1953 : * \param ctrlr The controller to check.
1954 : *
1955 : * \return a valid spdk_nvme_qp_failure_reason.
1956 : */
1957 : spdk_nvme_qp_failure_reason spdk_nvme_ctrlr_get_admin_qp_failure_reason(
1958 : struct spdk_nvme_ctrlr *ctrlr);
1959 :
1960 : /**
1961 : * Free an I/O queue pair that was allocated by spdk_nvme_ctrlr_alloc_io_qpair().
1962 : *
1963 : * The qpair must not be accessed after calling this function.
1964 : *
1965 : * \param qpair I/O queue pair to free.
1966 : *
1967 : * \return 0 on success. This function will never return any value other than 0.
1968 : */
1969 : int spdk_nvme_ctrlr_free_io_qpair(struct spdk_nvme_qpair *qpair);
1970 :
1971 : /**
1972 : * Send the given NVM I/O command, I/O buffers, lists and all to the NVMe controller.
1973 : *
1974 : * This is a low level interface for submitting I/O commands directly.
1975 : *
1976 : * This function allows a caller to submit an I/O request that is
1977 : * COMPLETELY pre-defined, right down to the "physical" memory buffers.
1978 : * It is intended for testing hardware, specifying exact buffer location,
1979 : * alignment, and offset. It also allows for specific choice of PRP
1980 : * and SGLs.
1981 : *
1982 : * The driver sets the CID. EVERYTHING else is assumed set by the caller.
1983 : * Needless to say, this is potentially extremely dangerous for both the host
1984 : * (accidental/malicious storage usage/corruption), and the device.
1985 : * Thus its intent is for very specific hardware testing and environment
1986 : * reproduction.
1987 : *
1988 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
1989 : * The user must ensure that only one thread submits I/O on a given qpair at any
1990 : * given time.
1991 : *
1992 : * This function can only be used on PCIe controllers and qpairs.
1993 : *
1994 : * \param ctrlr Opaque handle to NVMe controller.
1995 : * \param qpair I/O qpair to submit command.
1996 : * \param cmd NVM I/O command to submit.
1997 : * \param cb_fn Callback function invoked when the I/O command completes.
1998 : * \param cb_arg Argument passed to callback function.
1999 : *
2000 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
2001 : * -ENOMEM: The request cannot be allocated.
2002 : * -ENXIO: The qpair is failed at the transport level.
2003 : */
2004 :
2005 : int spdk_nvme_ctrlr_io_cmd_raw_no_payload_build(struct spdk_nvme_ctrlr *ctrlr,
2006 : struct spdk_nvme_qpair *qpair,
2007 : struct spdk_nvme_cmd *cmd,
2008 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2009 :
2010 : /**
2011 : * Send the given NVM I/O command to the NVMe controller.
2012 : *
2013 : * This is a low level interface for submitting I/O commands directly. Prefer
2014 : * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will
2015 : * not be checked!
2016 : *
2017 : * When constructing the nvme_command it is not necessary to fill out the PRP
2018 : * list/SGL or the CID. The driver will handle both of those for you.
2019 : *
2020 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
2021 : * The user must ensure that only one thread submits I/O on a given qpair at any
2022 : * given time.
2023 : *
2024 : * \param ctrlr Opaque handle to NVMe controller.
2025 : * \param qpair I/O qpair to submit command.
2026 : * \param cmd NVM I/O command to submit.
2027 : * \param buf Virtual memory address of a single physically contiguous buffer.
2028 : * \param len Size of buffer.
2029 : * \param cb_fn Callback function invoked when the I/O command completes.
2030 : * \param cb_arg Argument passed to callback function.
2031 : *
2032 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
2033 : * -ENOMEM: The request cannot be allocated.
2034 : * -ENXIO: The qpair is failed at the transport level.
2035 : */
2036 : int spdk_nvme_ctrlr_cmd_io_raw(struct spdk_nvme_ctrlr *ctrlr,
2037 : struct spdk_nvme_qpair *qpair,
2038 : struct spdk_nvme_cmd *cmd,
2039 : void *buf, uint32_t len,
2040 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2041 :
2042 : /**
2043 : * Send the given NVM I/O command with metadata to the NVMe controller.
2044 : *
2045 : * This is a low level interface for submitting I/O commands directly. Prefer
2046 : * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will
2047 : * not be checked!
2048 : *
2049 : * When constructing the nvme_command it is not necessary to fill out the PRP
2050 : * list/SGL or the CID. The driver will handle both of those for you.
2051 : *
2052 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
2053 : * The user must ensure that only one thread submits I/O on a given qpair at any
2054 : * given time.
2055 : *
2056 : * \param ctrlr Opaque handle to NVMe controller.
2057 : * \param qpair I/O qpair to submit command.
2058 : * \param cmd NVM I/O command to submit.
2059 : * \param buf Virtual memory address of a single physically contiguous buffer.
2060 : * \param len Size of buffer.
2061 : * \param md_buf Virtual memory address of a single physically contiguous metadata
2062 : * buffer.
2063 : * \param cb_fn Callback function invoked when the I/O command completes.
2064 : * \param cb_arg Argument passed to callback function.
2065 : *
2066 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
2067 : * -ENOMEM: The request cannot be allocated.
2068 : * -ENXIO: The qpair is failed at the transport level.
2069 : */
2070 : int spdk_nvme_ctrlr_cmd_io_raw_with_md(struct spdk_nvme_ctrlr *ctrlr,
2071 : struct spdk_nvme_qpair *qpair,
2072 : struct spdk_nvme_cmd *cmd,
2073 : void *buf, uint32_t len, void *md_buf,
2074 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2075 :
2076 : /**
2077 : * Restart the SGL walk to the specified offset when the command has scattered
2078 : * payloads.
2079 : *
2080 : * \param cb_arg Argument passed to readv/writev.
2081 : * \param offset Offset for SGL.
2082 : */
2083 : typedef void (*spdk_nvme_req_reset_sgl_cb)(void *cb_arg, uint32_t offset);
2084 :
2085 : /**
2086 : * Fill out *address and *length with the current SGL entry and advance to the
2087 : * next entry for the next time the callback is invoked.
2088 : *
2089 : * The described segment must be physically contiguous.
2090 : *
2091 : * \param cb_arg Argument passed to readv/writev.
2092 : * \param address Virtual address of this segment, a value of UINT64_MAX
2093 : * means the segment should be described via Bit Bucket SGL.
2094 : * \param length Length of this physical segment.
2095 : */
2096 : typedef int (*spdk_nvme_req_next_sge_cb)(void *cb_arg, void **address,
2097 : uint32_t *length);
2098 :
2099 : /**
2100 : * Send the given NVM I/O command with metadata to the NVMe controller.
2101 : *
2102 : * This is a low level interface for submitting I/O commands directly. Prefer
2103 : * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will
2104 : * not be checked!
2105 : *
2106 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
2107 : * The user must ensure that only one thread submits I/O on a given qpair at any
2108 : * given time.
2109 : *
2110 : * \param ctrlr Opaque handle to NVMe controller.
2111 : * \param qpair I/O qpair to submit command.
2112 : * \param cmd NVM I/O command to submit.
2113 : * \param len Size of buffer.
2114 : * \param md_buf Virtual memory address of a single physically contiguous metadata buffer.
2115 : * \param cb_fn Callback function invoked when the I/O command completes.
2116 : * \param cb_arg Argument passed to callback function.
2117 : * \param reset_sgl_fn Callback function to reset scattered payload.
2118 : * \param next_sge_fn Callback function to iterate each scattered payload memory segment.
2119 : *
2120 : * \return 0 if successfully submitted, negated errnos on the following error
2121 : conditions:
2122 : * -ENOMEM: The request cannot be allocated.
2123 : * -ENXIO: The qpair is failed at the transport level.
2124 : */
2125 : int spdk_nvme_ctrlr_cmd_iov_raw_with_md(struct spdk_nvme_ctrlr *ctrlr,
2126 : struct spdk_nvme_qpair *qpair,
2127 : struct spdk_nvme_cmd *cmd, uint32_t len,
2128 : void *md_buf, spdk_nvme_cmd_cb cb_fn,
2129 : void *cb_arg,
2130 : spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
2131 : spdk_nvme_req_next_sge_cb next_sge_fn);
2132 :
2133 : /**
2134 : * Get file descriptor for an I/O queue pair.
2135 : *
2136 : * Applications that enable interrupts for completion notification will register and unregister
2137 : * interrupt event source on its queue pair file descriptor. This function returns file descriptor
2138 : * for an I/O queue pair.
2139 : * This function also allows the transport layer to fill out event handler opts required by the
2140 : * application during interrupt registration phase.
2141 : *
2142 : * \param qpair Opaque handle of the queue pair for which fd has to be fetched.
2143 : * \param[out] opts Opaque event handler options to be filled by the transport, or NULL.
2144 : *
2145 : * \return a valid fd on success, with opts filled out if specified
2146 : * -ENOTSUP if transport does not support fetching fd for the queue pair.
2147 : * -EINVAL if opts is specified but its size is incorrect.
2148 : * -EINVAL if fds are not reserved, -1 if interrupts are not enabled for the qpair controller.
2149 : */
2150 : int spdk_nvme_qpair_get_fd(struct spdk_nvme_qpair *qpair,
2151 : struct spdk_event_handler_opts *opts);
2152 :
2153 : /**
2154 : * Process any outstanding completions for I/O submitted on a queue pair.
2155 : *
2156 : * This call is non-blocking, i.e. it only processes completions that are ready
2157 : * at the time of this function call. It does not wait for outstanding commands
2158 : * to finish.
2159 : *
2160 : * For each completed command, the request's callback function will be called if
2161 : * specified as non-NULL when the request was submitted.
2162 : *
2163 : * The caller must ensure that each queue pair is only used from one thread at a
2164 : * time.
2165 : *
2166 : * This function may be called at any point while the controller is attached to
2167 : * the SPDK NVMe driver.
2168 : *
2169 : * \sa spdk_nvme_cmd_cb
2170 : *
2171 : * \param qpair Queue pair to check for completions.
2172 : * \param max_completions Limit the number of completions to be processed in one
2173 : * call, or 0 for unlimited.
2174 : *
2175 : * \return number of completions processed (may be 0) or negated on error. -ENXIO
2176 : * in the special case that the qpair is failed at the transport layer.
2177 : */
2178 : int32_t spdk_nvme_qpair_process_completions(struct spdk_nvme_qpair *qpair,
2179 : uint32_t max_completions);
2180 :
2181 : /**
2182 : * Returns the reason the qpair is disconnected.
2183 : *
2184 : * \param qpair The qpair to check.
2185 : *
2186 : * \return a valid spdk_nvme_qp_failure_reason.
2187 : */
2188 : spdk_nvme_qp_failure_reason spdk_nvme_qpair_get_failure_reason(struct spdk_nvme_qpair *qpair);
2189 :
2190 : /**
2191 : * Control if DNR is set or not for aborted commands.
2192 : *
2193 : * The default value is false.
2194 : *
2195 : * \param qpair The qpair to set.
2196 : * \param dnr Set the DNR bit to 1 if true or 0 if false for aborted commands.
2197 : */
2198 : void spdk_nvme_qpair_set_abort_dnr(struct spdk_nvme_qpair *qpair, bool dnr);
2199 :
2200 : /**
2201 : * Return the connection status of a given qpair.
2202 : *
2203 : * \param qpair The qpair to check.
2204 : *
2205 : * \return true if the qpair is connected, or false otherwise.
2206 : */
2207 : bool spdk_nvme_qpair_is_connected(struct spdk_nvme_qpair *qpair);
2208 :
2209 : typedef void (*spdk_nvme_authenticate_cb)(void *ctx, int status);
2210 :
2211 : /**
2212 : * Force a qpair to authenticate. As part of initialization, qpairs are authenticated automatically
2213 : * if the controller is configured with DH-HMAC-CHAP keys. However, this function can be used to
2214 : * force authentication after a connection has already been established.
2215 : *
2216 : * This function doesn't disconnect the qpair if the authentication is successful.
2217 : *
2218 : * \param qpair The qpair to authenticate.
2219 : * \param cb_fn Callback to be executed after the authentication is done.
2220 : * \param cb_ctx Context passed to `cb_fn`.
2221 : *
2222 : * \return 0 on success, negative errno on failure.
2223 : */
2224 : int spdk_nvme_qpair_authenticate(struct spdk_nvme_qpair *qpair,
2225 : spdk_nvme_authenticate_cb cb_fn, void *cb_ctx);
2226 :
2227 : /**
2228 : * Force authentication on the admin qpair of a controller. As part of initialization, the admin
2229 : * qpair is authenticated automatically if the controller is configured with DH-HMAC-CHAP keys.
2230 : * However, this function can be used to force authentication after a connection has already been
2231 : * established.
2232 : *
2233 : * This function doesn't disconnect the admin qpair if the authentication is successful.
2234 : *
2235 : * \param ctrlr Controller to authenticate.
2236 : * \param cb_fn Callback to be executed after the authentication is done.
2237 : * \param cb_ctx Context passed to `cb_fn`.
2238 : *
2239 : * \return 0 on success, negative errno on failure.
2240 : */
2241 : int spdk_nvme_ctrlr_authenticate(struct spdk_nvme_ctrlr *ctrlr,
2242 : spdk_nvme_authenticate_cb cb_fn, void *cb_ctx);
2243 :
2244 : /**
2245 : * Send the given admin command to the NVMe controller.
2246 : *
2247 : * This is a low level interface for submitting admin commands directly. Prefer
2248 : * the spdk_nvme_ctrlr_cmd_* functions instead. The validity of the command will
2249 : * not be checked!
2250 : *
2251 : * When constructing the nvme_command it is not necessary to fill out the PRP
2252 : * list/SGL or the CID. The driver will handle both of those for you.
2253 : *
2254 : * This function is thread safe and can be called at any point while the controller
2255 : * is attached to the SPDK NVMe driver.
2256 : *
2257 : * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion
2258 : * of commands submitted through this function.
2259 : *
2260 : * \param ctrlr Opaque handle to NVMe controller.
2261 : * \param cmd NVM admin command to submit.
2262 : * \param buf Virtual memory address of a single physically contiguous buffer.
2263 : * \param len Size of buffer.
2264 : * \param cb_fn Callback function invoked when the admin command completes.
2265 : * \param cb_arg Argument passed to callback function.
2266 : *
2267 : * \return 0 if successfully submitted, negated errno if resources could not be
2268 : * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
2269 : */
2270 : int spdk_nvme_ctrlr_cmd_admin_raw(struct spdk_nvme_ctrlr *ctrlr,
2271 : struct spdk_nvme_cmd *cmd,
2272 : void *buf, uint32_t len,
2273 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2274 :
2275 : /**
2276 : * Process any outstanding completions for admin commands.
2277 : *
2278 : * This will process completions for admin commands submitted on any thread.
2279 : *
2280 : * This call is non-blocking, i.e. it only processes completions that are ready
2281 : * at the time of this function call. It does not wait for outstanding commands
2282 : * to finish.
2283 : *
2284 : * This function is thread safe and can be called at any point while the controller
2285 : * is attached to the SPDK NVMe driver.
2286 : *
2287 : * \param ctrlr Opaque handle to NVMe controller.
2288 : *
2289 : * \return number of completions processed (may be 0) or negated on error. -ENXIO
2290 : * in the special case that the qpair is failed at the transport layer.
2291 : */
2292 : int32_t spdk_nvme_ctrlr_process_admin_completions(struct spdk_nvme_ctrlr *ctrlr);
2293 :
2294 :
2295 : /**
2296 : * Opaque handle to a namespace. Obtained by calling spdk_nvme_ctrlr_get_ns().
2297 : */
2298 : struct spdk_nvme_ns;
2299 :
2300 : /**
2301 : * Get a handle to a namespace for the given controller.
2302 : *
2303 : * Namespaces are numbered from 1 to the total number of namespaces. There will
2304 : * never be any gaps in the numbering. The number of namespaces is obtained by
2305 : * calling spdk_nvme_ctrlr_get_num_ns().
2306 : *
2307 : * This function is thread safe and can be called at any point while the controller
2308 : * is attached to the SPDK NVMe driver.
2309 : *
2310 : * \param ctrlr Opaque handle to NVMe controller.
2311 : * \param ns_id Namespace id.
2312 : *
2313 : * \return a pointer to the namespace.
2314 : */
2315 : struct spdk_nvme_ns *spdk_nvme_ctrlr_get_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t ns_id);
2316 :
2317 : /**
2318 : * Get a specific log page from the NVMe controller.
2319 : *
2320 : * This function is thread safe and can be called at any point while the controller
2321 : * is attached to the SPDK NVMe driver.
2322 : *
2323 : * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
2324 : * commands submitted through this function.
2325 : *
2326 : * \sa spdk_nvme_ctrlr_is_log_page_supported()
2327 : *
2328 : * \param ctrlr Opaque handle to NVMe controller.
2329 : * \param log_page The log page identifier.
2330 : * \param nsid Depending on the log page, this may be 0, a namespace identifier,
2331 : * or SPDK_NVME_GLOBAL_NS_TAG.
2332 : * \param payload The pointer to the payload buffer.
2333 : * \param payload_size The size of payload buffer.
2334 : * \param offset Offset in bytes within the log page to start retrieving log page
2335 : * data. May only be non-zero if the controller supports extended data for Get Log
2336 : * Page as reported in the controller data log page attributes.
2337 : * \param cb_fn Callback function to invoke when the log page has been retrieved.
2338 : * \param cb_arg Argument to pass to the callback function.
2339 : *
2340 : * \return 0 if successfully submitted, negated errno if resources could not be
2341 : * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
2342 : */
2343 : int spdk_nvme_ctrlr_cmd_get_log_page(struct spdk_nvme_ctrlr *ctrlr,
2344 : uint8_t log_page, uint32_t nsid,
2345 : void *payload, uint32_t payload_size,
2346 : uint64_t offset,
2347 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2348 :
2349 : /**
2350 : * Get a specific log page from the NVMe controller.
2351 : *
2352 : * This function is thread safe and can be called at any point while the controller
2353 : * is attached to the SPDK NVMe driver.
2354 : *
2355 : * This function allows specifying extra fields in cdw10 and cdw11 such as
2356 : * Retain Asynchronous Event and Log Specific Field.
2357 : *
2358 : * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
2359 : * commands submitted through this function.
2360 : *
2361 : * \sa spdk_nvme_ctrlr_is_log_page_supported()
2362 : *
2363 : * \param ctrlr Opaque handle to NVMe controller.
2364 : * \param log_page The log page identifier.
2365 : * \param nsid Depending on the log page, this may be 0, a namespace identifier,
2366 : * or SPDK_NVME_GLOBAL_NS_TAG.
2367 : * \param payload The pointer to the payload buffer.
2368 : * \param payload_size The size of payload buffer.
2369 : * \param offset Offset in bytes within the log page to start retrieving log page
2370 : * data. May only be non-zero if the controller supports extended data for Get Log
2371 : * Page as reported in the controller data log page attributes.
2372 : * \param cdw10 Value to specify for cdw10. Specify 0 for numdl - it will be
2373 : * set by this function based on the payload_size parameter. Specify 0 for lid -
2374 : * it will be set by this function based on the log_page parameter.
2375 : * \param cdw11 Value to specify for cdw11. Specify 0 for numdu - it will be
2376 : * set by this function based on the payload_size.
2377 : * \param cdw14 Value to specify for cdw14.
2378 : * \param cb_fn Callback function to invoke when the log page has been retrieved.
2379 : * \param cb_arg Argument to pass to the callback function.
2380 : *
2381 : * \return 0 if successfully submitted, negated errno if resources could not be
2382 : * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
2383 : */
2384 : int spdk_nvme_ctrlr_cmd_get_log_page_ext(struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page,
2385 : uint32_t nsid, void *payload, uint32_t payload_size,
2386 : uint64_t offset, uint32_t cdw10, uint32_t cdw11,
2387 : uint32_t cdw14, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2388 :
2389 : /**
2390 : * Abort a specific previously-submitted NVMe command.
2391 : *
2392 : * \sa spdk_nvme_ctrlr_register_timeout_callback()
2393 : *
2394 : * \param ctrlr NVMe controller to which the command was submitted.
2395 : * \param qpair NVMe queue pair to which the command was submitted. For admin
2396 : * commands, pass NULL for the qpair.
2397 : * \param cid Command ID of the command to abort.
2398 : * \param cb_fn Callback function to invoke when the abort has completed.
2399 : * \param cb_arg Argument to pass to the callback function.
2400 : *
2401 : * \return 0 if successfully submitted, negated errno if resources could not be
2402 : * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
2403 : */
2404 : int spdk_nvme_ctrlr_cmd_abort(struct spdk_nvme_ctrlr *ctrlr,
2405 : struct spdk_nvme_qpair *qpair,
2406 : uint16_t cid,
2407 : spdk_nvme_cmd_cb cb_fn,
2408 : void *cb_arg);
2409 :
2410 : /**
2411 : * Abort previously submitted commands which have cmd_cb_arg as its callback argument.
2412 : *
2413 : * \param ctrlr NVMe controller to which the commands were submitted.
2414 : * \param qpair NVMe queue pair to which the commands were submitted. For admin
2415 : * commands, pass NULL for the qpair.
2416 : * \param cmd_cb_arg Callback argument for the NVMe commands which this function
2417 : * attempts to abort.
2418 : * \param cb_fn Callback function to invoke when this function has completed.
2419 : * \param cb_arg Argument to pass to the callback function.
2420 : *
2421 : * \return 0 if successfully submitted, negated errno otherwise.
2422 : */
2423 : int spdk_nvme_ctrlr_cmd_abort_ext(struct spdk_nvme_ctrlr *ctrlr,
2424 : struct spdk_nvme_qpair *qpair,
2425 : void *cmd_cb_arg,
2426 : spdk_nvme_cmd_cb cb_fn,
2427 : void *cb_arg);
2428 :
2429 : /**
2430 : * Set specific feature for the given NVMe controller.
2431 : *
2432 : * This function is thread safe and can be called at any point while the controller
2433 : * is attached to the SPDK NVMe driver.
2434 : *
2435 : * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
2436 : * commands submitted through this function.
2437 : *
2438 : * \sa spdk_nvme_ctrlr_cmd_get_feature().
2439 : *
2440 : * \param ctrlr NVMe controller to manipulate.
2441 : * \param feature The feature identifier.
2442 : * \param cdw11 as defined by the specification for this command.
2443 : * \param cdw12 as defined by the specification for this command.
2444 : * \param payload The pointer to the payload buffer.
2445 : * \param payload_size The size of payload buffer.
2446 : * \param cb_fn Callback function to invoke when the feature has been set.
2447 : * \param cb_arg Argument to pass to the callback function.
2448 : *
2449 : * \return 0 if successfully submitted, negated errno if resources could not be
2450 : * allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.
2451 : */
2452 : int spdk_nvme_ctrlr_cmd_set_feature(struct spdk_nvme_ctrlr *ctrlr,
2453 : uint8_t feature, uint32_t cdw11, uint32_t cdw12,
2454 : void *payload, uint32_t payload_size,
2455 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2456 :
2457 : /**
2458 : * Get specific feature from given NVMe controller.
2459 : *
2460 : * This function is thread safe and can be called at any point while the controller
2461 : * is attached to the SPDK NVMe driver.
2462 : *
2463 : * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
2464 : * commands submitted through this function.
2465 : *
2466 : * \sa spdk_nvme_ctrlr_cmd_set_feature()
2467 : *
2468 : * \param ctrlr NVMe controller to query.
2469 : * \param feature The feature identifier.
2470 : * \param cdw11 as defined by the specification for this command.
2471 : * \param payload The pointer to the payload buffer.
2472 : * \param payload_size The size of payload buffer.
2473 : * \param cb_fn Callback function to invoke when the feature has been retrieved.
2474 : * \param cb_arg Argument to pass to the callback function.
2475 : *
2476 : * \return 0 if successfully submitted, -ENOMEM if resources could not be allocated
2477 : * for this request, -ENXIO if the admin qpair is failed at the transport layer.
2478 : */
2479 : int spdk_nvme_ctrlr_cmd_get_feature(struct spdk_nvme_ctrlr *ctrlr,
2480 : uint8_t feature, uint32_t cdw11,
2481 : void *payload, uint32_t payload_size,
2482 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2483 :
2484 : /**
2485 : * Get specific feature from given NVMe controller.
2486 : *
2487 : * \param ctrlr NVMe controller to query.
2488 : * \param feature The feature identifier.
2489 : * \param cdw11 as defined by the specification for this command.
2490 : * \param payload The pointer to the payload buffer.
2491 : * \param payload_size The size of payload buffer.
2492 : * \param cb_fn Callback function to invoke when the feature has been retrieved.
2493 : * \param cb_arg Argument to pass to the callback function.
2494 : * \param ns_id The namespace identifier.
2495 : *
2496 : * \return 0 if successfully submitted, -ENOMEM if resources could not be allocated
2497 : * for this request, -ENXIO if the admin qpair is failed at the transport layer.
2498 : *
2499 : * This function is thread safe and can be called at any point while the controller
2500 : * is attached to the SPDK NVMe driver.
2501 : *
2502 : * Call \ref spdk_nvme_ctrlr_process_admin_completions() to poll for completion
2503 : * of commands submitted through this function.
2504 : *
2505 : * \sa spdk_nvme_ctrlr_cmd_set_feature_ns()
2506 : */
2507 : int spdk_nvme_ctrlr_cmd_get_feature_ns(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature,
2508 : uint32_t cdw11, void *payload, uint32_t payload_size,
2509 : spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t ns_id);
2510 :
2511 : /**
2512 : * Set specific feature for the given NVMe controller and namespace ID.
2513 : *
2514 : * \param ctrlr NVMe controller to manipulate.
2515 : * \param feature The feature identifier.
2516 : * \param cdw11 as defined by the specification for this command.
2517 : * \param cdw12 as defined by the specification for this command.
2518 : * \param payload The pointer to the payload buffer.
2519 : * \param payload_size The size of payload buffer.
2520 : * \param cb_fn Callback function to invoke when the feature has been set.
2521 : * \param cb_arg Argument to pass to the callback function.
2522 : * \param ns_id The namespace identifier.
2523 : *
2524 : * \return 0 if successfully submitted, -ENOMEM if resources could not be allocated
2525 : * for this request, -ENXIO if the admin qpair is failed at the transport layer.
2526 : *
2527 : * This function is thread safe and can be called at any point while the controller
2528 : * is attached to the SPDK NVMe driver.
2529 : *
2530 : * Call \ref spdk_nvme_ctrlr_process_admin_completions() to poll for completion
2531 : * of commands submitted through this function.
2532 : *
2533 : * \sa spdk_nvme_ctrlr_cmd_get_feature_ns()
2534 : */
2535 : int spdk_nvme_ctrlr_cmd_set_feature_ns(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature,
2536 : uint32_t cdw11, uint32_t cdw12, void *payload,
2537 : uint32_t payload_size, spdk_nvme_cmd_cb cb_fn,
2538 : void *cb_arg, uint32_t ns_id);
2539 :
2540 : /**
2541 : * Receive security protocol data from controller.
2542 : *
2543 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2544 : *
2545 : * \param ctrlr NVMe controller to use for security receive command submission.
2546 : * \param secp Security Protocol that is used.
2547 : * \param spsp Security Protocol Specific field.
2548 : * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
2549 : * Protocol EAh.
2550 : * \param payload The pointer to the payload buffer.
2551 : * \param payload_size The size of payload buffer.
2552 : * \param cb_fn Callback function to invoke when the command has been completed.
2553 : * \param cb_arg Argument to pass to the callback function.
2554 : *
2555 : * \return 0 if successfully submitted, negated errno if resources could not be allocated
2556 : * for this request.
2557 : */
2558 : int spdk_nvme_ctrlr_cmd_security_receive(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
2559 : uint16_t spsp, uint8_t nssf, void *payload,
2560 : uint32_t payload_size,
2561 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2562 :
2563 : /**
2564 : * Send security protocol data to controller.
2565 : *
2566 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2567 : *
2568 : * \param ctrlr NVMe controller to use for security send command submission.
2569 : * \param secp Security Protocol that is used.
2570 : * \param spsp Security Protocol Specific field.
2571 : * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
2572 : * Protocol EAh.
2573 : * \param payload The pointer to the payload buffer.
2574 : * \param payload_size The size of payload buffer.
2575 : * \param cb_fn Callback function to invoke when the command has been completed.
2576 : * \param cb_arg Argument to pass to the callback function.
2577 : *
2578 : * \return 0 if successfully submitted, negated errno if resources could not be allocated
2579 : * for this request.
2580 : */
2581 : int spdk_nvme_ctrlr_cmd_security_send(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
2582 : uint16_t spsp, uint8_t nssf, void *payload,
2583 : uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2584 :
2585 : /**
2586 : * Receive security protocol data from controller.
2587 : *
2588 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2589 : *
2590 : * \param ctrlr NVMe controller to use for security receive command submission.
2591 : * \param secp Security Protocol that is used.
2592 : * \param spsp Security Protocol Specific field.
2593 : * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
2594 : * Protocol EAh.
2595 : * \param payload The pointer to the payload buffer.
2596 : * \param size The size of payload buffer.
2597 : *
2598 : * \return 0 if successfully submitted, negated errno if resources could not be allocated
2599 : * for this request.
2600 : */
2601 : int spdk_nvme_ctrlr_security_receive(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
2602 : uint16_t spsp, uint8_t nssf, void *payload, size_t size);
2603 :
2604 : /**
2605 : * Send security protocol data to controller.
2606 : *
2607 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2608 : *
2609 : * \param ctrlr NVMe controller to use for security send command submission.
2610 : * \param secp Security Protocol that is used.
2611 : * \param spsp Security Protocol Specific field.
2612 : * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security
2613 : * Protocol EAh.
2614 : * \param payload The pointer to the payload buffer.
2615 : * \param size The size of payload buffer.
2616 : *
2617 : * \return 0 if successfully submitted, negated errno if resources could not be allocated
2618 : * for this request.
2619 : */
2620 : int spdk_nvme_ctrlr_security_send(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp,
2621 : uint16_t spsp, uint8_t nssf, void *payload, size_t size);
2622 :
2623 : /**
2624 : * Receive data related to a specific Directive Type from the controller.
2625 : *
2626 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2627 : *
2628 : * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
2629 : * commands submitted through this function.
2630 : *
2631 : * \param ctrlr NVMe controller to use for directive receive command submission.
2632 : * \param nsid Specific Namespace Identifier.
2633 : * \param doper Directive Operation defined in nvme_spec.h.
2634 : * \param dtype Directive Type defined in nvme_spec.h.
2635 : * \param dspec Directive Specific defined in nvme_spec.h.
2636 : * \param payload The pointer to the payload buffer.
2637 : * \param payload_size The size of payload buffer.
2638 : * \param cdw12 Command dword 12.
2639 : * \param cdw13 Command dword 13.
2640 : * \param cb_fn Callback function to invoke when the command has been completed.
2641 : * \param cb_arg Argument to pass to the callback function.
2642 : *
2643 : * \return 0 if successfully submitted, negated errno if resources could not be allocated
2644 : * for this request.
2645 : */
2646 : int spdk_nvme_ctrlr_cmd_directive_receive(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
2647 : uint32_t doper, uint32_t dtype, uint32_t dspec,
2648 : void *payload, uint32_t payload_size, uint32_t cdw12,
2649 : uint32_t cdw13, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2650 :
2651 : /**
2652 : * Send data related to a specific Directive Type to the controller.
2653 : *
2654 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2655 : *
2656 : * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of
2657 : * commands submitted through this function.
2658 : *
2659 : * \param ctrlr NVMe controller to use for directive send command submission.
2660 : * \param nsid Specific Namespace Identifier.
2661 : * \param doper Directive Operation defined in nvme_spec.h.
2662 : * \param dtype Directive Type defined in nvme_spec.h.
2663 : * \param dspec Directive Specific defined in nvme_spec.h.
2664 : * \param payload The pointer to the payload buffer.
2665 : * \param payload_size The size of payload buffer.
2666 : * \param cdw12 Command dword 12.
2667 : * \param cdw13 Command dword 13.
2668 : * \param cb_fn Callback function to invoke when the command has been completed.
2669 : * \param cb_arg Argument to pass to the callback function.
2670 : *
2671 : * \return 0 if successfully submitted, negated errno if resources could not be allocated
2672 : * for this request.
2673 : */
2674 : int spdk_nvme_ctrlr_cmd_directive_send(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
2675 : uint32_t doper, uint32_t dtype, uint32_t dspec,
2676 : void *payload, uint32_t payload_size, uint32_t cdw12,
2677 : uint32_t cdw13, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2678 :
2679 : /**
2680 : * Get supported flags of the controller.
2681 : *
2682 : * \param ctrlr NVMe controller to get flags.
2683 : *
2684 : * \return supported flags of this controller.
2685 : */
2686 : uint64_t spdk_nvme_ctrlr_get_flags(struct spdk_nvme_ctrlr *ctrlr);
2687 :
2688 : /**
2689 : * Attach the specified namespace to controllers.
2690 : *
2691 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2692 : *
2693 : * \param ctrlr NVMe controller to use for command submission.
2694 : * \param nsid Namespace identifier for namespace to attach.
2695 : * \param payload The pointer to the controller list.
2696 : *
2697 : * \return 0 if successfully submitted, ENOMEM if resources could not be allocated
2698 : * for this request.
2699 : */
2700 : int spdk_nvme_ctrlr_attach_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
2701 : struct spdk_nvme_ctrlr_list *payload);
2702 :
2703 : /**
2704 : * Detach the specified namespace from controllers.
2705 : *
2706 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2707 : *
2708 : * \param ctrlr NVMe controller to use for command submission.
2709 : * \param nsid Namespace ID to detach.
2710 : * \param payload The pointer to the controller list.
2711 : *
2712 : * \return 0 if successfully submitted, ENOMEM if resources could not be allocated
2713 : * for this request
2714 : */
2715 : int spdk_nvme_ctrlr_detach_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
2716 : struct spdk_nvme_ctrlr_list *payload);
2717 :
2718 : /**
2719 : * Create a namespace.
2720 : *
2721 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2722 : *
2723 : * \param ctrlr NVMe controller to create namespace on.
2724 : * \param payload The pointer to the NVMe namespace data.
2725 : *
2726 : * \return Namespace ID (>= 1) if successfully created, or 0 if the request failed.
2727 : */
2728 : uint32_t spdk_nvme_ctrlr_create_ns(struct spdk_nvme_ctrlr *ctrlr,
2729 : struct spdk_nvme_ns_data *payload);
2730 :
2731 : /**
2732 : * Delete a namespace.
2733 : *
2734 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2735 : *
2736 : * \param ctrlr NVMe controller to delete namespace from.
2737 : * \param nsid The namespace identifier.
2738 : *
2739 : * \return 0 if successfully submitted, negated errno if resources could not be
2740 : * allocated
2741 : * for this request
2742 : */
2743 : int spdk_nvme_ctrlr_delete_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid);
2744 :
2745 : /**
2746 : * Format NVM.
2747 : *
2748 : * This function requests a low-level format of the media.
2749 : *
2750 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2751 : *
2752 : * \param ctrlr NVMe controller to format.
2753 : * \param nsid The namespace identifier. May be SPDK_NVME_GLOBAL_NS_TAG to format
2754 : * all namespaces.
2755 : * \param format The format information for the command.
2756 : *
2757 : * \return 0 if successfully submitted, negated errno if resources could not be
2758 : * allocated for this request
2759 : */
2760 : int spdk_nvme_ctrlr_format(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
2761 : struct spdk_nvme_format *format);
2762 :
2763 : /**
2764 : * Download a new firmware image.
2765 : *
2766 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2767 : *
2768 : * \param ctrlr NVMe controller to perform firmware operation on.
2769 : * \param payload The data buffer for the firmware image.
2770 : * \param size The data size will be downloaded.
2771 : * \param slot The slot that the firmware image will be committed to.
2772 : * \param commit_action The action to perform when firmware is committed.
2773 : * \param completion_status output parameter. Contains the completion status of
2774 : * the firmware commit operation.
2775 : *
2776 : * \return 0 if successfully submitted, ENOMEM if resources could not be allocated
2777 : * for this request, -1 if the size is not multiple of 4.
2778 : */
2779 : int spdk_nvme_ctrlr_update_firmware(struct spdk_nvme_ctrlr *ctrlr, void *payload, uint32_t size,
2780 : int slot, enum spdk_nvme_fw_commit_action commit_action,
2781 : struct spdk_nvme_status *completion_status);
2782 :
2783 : /**
2784 : * Start the Read from a Boot Partition.
2785 : *
2786 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2787 : *
2788 : * \param ctrlr NVMe controller to perform the Boot Partition read.
2789 : * \param payload The data buffer for Boot Partition read.
2790 : * \param bprsz Read size in multiples of 4 KiB to copy into the Boot Partition Memory Buffer.
2791 : * \param bprof Boot Partition offset to read from in 4 KiB units.
2792 : * \param bpid Boot Partition identifier for the Boot Partition read operation.
2793 : *
2794 : * \return 0 if Boot Partition read is successful. Negated errno on the following error conditions:
2795 : * -ENOMEM: if resources could not be allocated.
2796 : * -ENOTSUP: Boot Partition is not supported by the Controller.
2797 : * -EIO: Registers access failure.
2798 : * -EINVAL: Parameters are invalid.
2799 : * -EFAULT: Invalid address was specified as part of payload.
2800 : * -EALREADY: Boot Partition read already initiated.
2801 : */
2802 : int spdk_nvme_ctrlr_read_boot_partition_start(struct spdk_nvme_ctrlr *ctrlr, void *payload,
2803 : uint32_t bprsz, uint32_t bprof, uint32_t bpid);
2804 :
2805 : /**
2806 : * Poll the status of the Read from a Boot Partition.
2807 : *
2808 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2809 : *
2810 : * \param ctrlr NVMe controller to perform the Boot Partition read.
2811 : *
2812 : * \return 0 if Boot Partition read is successful. Negated errno on the following error conditions:
2813 : * -EIO: Registers access failure.
2814 : * -EINVAL: Invalid read status or the Boot Partition read is not initiated yet.
2815 : * -EAGAIN: If the read is still in progress; users must call
2816 : * spdk_nvme_ctrlr_read_boot_partition_poll again to check the read status.
2817 : */
2818 : int spdk_nvme_ctrlr_read_boot_partition_poll(struct spdk_nvme_ctrlr *ctrlr);
2819 :
2820 : /**
2821 : * Write to a Boot Partition.
2822 : *
2823 : * This function is thread safe and can be called at any point after spdk_nvme_probe().
2824 : * Users will get the completion after the data is downloaded, image is replaced and
2825 : * Boot Partition is activated or when the sequence encounters an error.
2826 : *
2827 : * \param ctrlr NVMe controller to perform the Boot Partition write.
2828 : * \param payload The data buffer for Boot Partition write.
2829 : * \param size Data size to write to the Boot Partition.
2830 : * \param bpid Boot Partition identifier for the Boot Partition write operation.
2831 : * \param cb_fn Callback function to invoke when the operation is completed.
2832 : * \param cb_arg Argument to pass to the callback function.
2833 : *
2834 : * \return 0 if Boot Partition write submit is successful. Negated errno on the following error conditions:
2835 : * -ENOMEM: if resources could not be allocated.
2836 : * -ENOTSUP: Boot Partition is not supported by the Controller.
2837 : * -EIO: Registers access failure.
2838 : * -EINVAL: Parameters are invalid.
2839 : */
2840 : int spdk_nvme_ctrlr_write_boot_partition(struct spdk_nvme_ctrlr *ctrlr, void *payload,
2841 : uint32_t size, uint32_t bpid, spdk_nvme_cmd_cb cb_fn, void *cb_arg);
2842 :
2843 : /**
2844 : * Return virtual address of PCIe NVM I/O registers
2845 : *
2846 : * This function returns a pointer to the PCIe I/O registers for a controller
2847 : * or NULL if unsupported for this transport.
2848 : *
2849 : * \param ctrlr Controller whose registers are to be accessed.
2850 : *
2851 : * \return Pointer to virtual address of register bank, or NULL.
2852 : */
2853 : volatile struct spdk_nvme_registers *spdk_nvme_ctrlr_get_registers(struct spdk_nvme_ctrlr *ctrlr);
2854 :
2855 : /**
2856 : * Reserve the controller memory buffer for data transfer use.
2857 : *
2858 : * This function reserves the full size of the controller memory buffer
2859 : * for use in data transfers. If submission queues or completion queues are
2860 : * already placed in the controller memory buffer, this call will fail.
2861 : *
2862 : * \param ctrlr Controller from which to allocate memory buffer
2863 : *
2864 : * \return The size of the controller memory buffer on success. Negated errno
2865 : * on failure.
2866 : */
2867 : int spdk_nvme_ctrlr_reserve_cmb(struct spdk_nvme_ctrlr *ctrlr);
2868 :
2869 : /**
2870 : * Map a previously reserved controller memory buffer so that it's data is
2871 : * visible from the CPU. This operation is not always possible.
2872 : *
2873 : * \param ctrlr Controller that contains the memory buffer
2874 : * \param size Size of buffer that was mapped.
2875 : *
2876 : * \return Pointer to controller memory buffer, or NULL on failure.
2877 : */
2878 : void *spdk_nvme_ctrlr_map_cmb(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
2879 :
2880 : /**
2881 : * Free a controller memory I/O buffer.
2882 : *
2883 : * \param ctrlr Controller from which to unmap the memory buffer.
2884 : */
2885 : void spdk_nvme_ctrlr_unmap_cmb(struct spdk_nvme_ctrlr *ctrlr);
2886 :
2887 : /**
2888 : * Enable the Persistent Memory Region
2889 : *
2890 : * \param ctrlr Controller that contains the Persistent Memory Region
2891 : *
2892 : * \return 0 on success. Negated errno on the following error conditions:
2893 : * -ENOTSUP: PMR is not supported by the Controller.
2894 : * -EIO: Registers access failure.
2895 : * -EINVAL: PMR Time Units Invalid or PMR is already enabled.
2896 : * -ETIMEDOUT: Timed out to Enable PMR.
2897 : * -ENOSYS: Transport does not support Enable PMR function.
2898 : */
2899 : int spdk_nvme_ctrlr_enable_pmr(struct spdk_nvme_ctrlr *ctrlr);
2900 :
2901 : /**
2902 : * Disable the Persistent Memory Region
2903 : *
2904 : * \param ctrlr Controller that contains the Persistent Memory Region
2905 : *
2906 : * \return 0 on success. Negated errno on the following error conditions:
2907 : * -ENOTSUP: PMR is not supported by the Controller.
2908 : * -EIO: Registers access failure.
2909 : * -EINVAL: PMR Time Units Invalid or PMR is already disabled.
2910 : * -ETIMEDOUT: Timed out to Disable PMR.
2911 : * -ENOSYS: Transport does not support Disable PMR function.
2912 : */
2913 : int spdk_nvme_ctrlr_disable_pmr(struct spdk_nvme_ctrlr *ctrlr);
2914 :
2915 : /**
2916 : * Map the Persistent Memory Region so that it's data is
2917 : * visible from the CPU.
2918 : *
2919 : * \param ctrlr Controller that contains the Persistent Memory Region
2920 : * \param size Size of the region that was mapped.
2921 : *
2922 : * \return Pointer to Persistent Memory Region, or NULL on failure.
2923 : */
2924 : void *spdk_nvme_ctrlr_map_pmr(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
2925 :
2926 : /**
2927 : * Free the Persistent Memory Region.
2928 : *
2929 : * \param ctrlr Controller from which to unmap the Persistent Memory Region.
2930 : *
2931 : * \return 0 on success, negative errno on failure.
2932 : * -ENXIO: Either PMR is not supported by the Controller or the PMR is already unmapped.
2933 : * -ENOSYS: Transport does not support Unmap PMR function.
2934 : */
2935 : int spdk_nvme_ctrlr_unmap_pmr(struct spdk_nvme_ctrlr *ctrlr);
2936 :
2937 : /**
2938 : * Get the transport ID for a given NVMe controller.
2939 : *
2940 : * \param ctrlr Controller to get the transport ID.
2941 : * \return Pointer to the controller's transport ID.
2942 : */
2943 : const struct spdk_nvme_transport_id *spdk_nvme_ctrlr_get_transport_id(
2944 : struct spdk_nvme_ctrlr *ctrlr);
2945 :
2946 : /**
2947 : * \brief Alloc NVMe I/O queue identifier.
2948 : *
2949 : * This function is only needed for the non-standard case of allocating queues using the raw
2950 : * command interface. In most cases \ref spdk_nvme_ctrlr_alloc_io_qpair should be sufficient.
2951 : *
2952 : * \param ctrlr Opaque handle to NVMe controller.
2953 : * \return qid on success, -1 on failure.
2954 : */
2955 : int32_t spdk_nvme_ctrlr_alloc_qid(struct spdk_nvme_ctrlr *ctrlr);
2956 :
2957 : /**
2958 : * \brief Free NVMe I/O queue identifier.
2959 : *
2960 : * This function must only be called with qids previously allocated with \ref spdk_nvme_ctrlr_alloc_qid.
2961 : *
2962 : * \param ctrlr Opaque handle to NVMe controller.
2963 : * \param qid NVMe Queue Identifier.
2964 : */
2965 : void spdk_nvme_ctrlr_free_qid(struct spdk_nvme_ctrlr *ctrlr, uint16_t qid);
2966 :
2967 : /**
2968 : * Opaque handle for a poll group. A poll group is a collection of spdk_nvme_qpair
2969 : * objects that are polled for completions as a unit.
2970 : *
2971 : * Returned by spdk_nvme_poll_group_create().
2972 : */
2973 : struct spdk_nvme_poll_group;
2974 :
2975 :
2976 : /**
2977 : * This function alerts the user to disconnected qpairs when calling
2978 : * spdk_nvme_poll_group_process_completions.
2979 : */
2980 : typedef void (*spdk_nvme_disconnected_qpair_cb)(struct spdk_nvme_qpair *qpair,
2981 : void *poll_group_ctx);
2982 :
2983 : /**
2984 : * Create a new poll group.
2985 : *
2986 : * \param ctx A user supplied context that can be retrieved later with spdk_nvme_poll_group_get_ctx
2987 : * \param table The call back table defined by users which contains the accelerated functions
2988 : * which can be used to accelerate some operations such as crc32c.
2989 : *
2990 : * \return Pointer to the new poll group, or NULL on error.
2991 : */
2992 : struct spdk_nvme_poll_group *spdk_nvme_poll_group_create(void *ctx,
2993 : struct spdk_nvme_accel_fn_table *table);
2994 :
2995 : /**
2996 : * Get a optimal poll group.
2997 : *
2998 : * \param qpair The qpair to get the optimal poll group.
2999 : *
3000 : * \return Pointer to the optimal poll group, or NULL if not found.
3001 : */
3002 : struct spdk_nvme_poll_group *spdk_nvme_qpair_get_optimal_poll_group(struct spdk_nvme_qpair *qpair);
3003 :
3004 : /**
3005 : * Add an spdk_nvme_qpair to a poll group. qpairs may only be added to
3006 : * a poll group if they are in the disconnected state; i.e. either they were
3007 : * just allocated and not yet connected or they have been disconnected with a call
3008 : * to spdk_nvme_ctrlr_disconnect_io_qpair.
3009 : *
3010 : * \param group The group to which the qpair will be added.
3011 : * \param qpair The qpair to add to the poll group.
3012 : *
3013 : * return 0 on success, -EINVAL if the qpair is not in the disabled state, -ENODEV if the transport
3014 : * doesn't exist, -ENOMEM on memory allocation failures, or -EPROTO on a protocol (transport) specific failure.
3015 : */
3016 : int spdk_nvme_poll_group_add(struct spdk_nvme_poll_group *group, struct spdk_nvme_qpair *qpair);
3017 :
3018 : /**
3019 : * Remove a disconnected spdk_nvme_qpair from a poll group.
3020 : *
3021 : * \param group The group from which to remove the qpair.
3022 : * \param qpair The qpair to remove from the poll group.
3023 : *
3024 : * return 0 on success, -ENOENT if the qpair is not found in the group, -EINVAL if the qpair is not
3025 : * disconnected in the group, or -EPROTO on a protocol (transport) specific failure.
3026 : */
3027 : int spdk_nvme_poll_group_remove(struct spdk_nvme_poll_group *group, struct spdk_nvme_qpair *qpair);
3028 :
3029 : /**
3030 : * Wait for interrupt events on file descriptors of all the qpairs in this poll group.
3031 : *
3032 : * In interrupt mode all the file descriptors of qpairs are registered to the fd group within the
3033 : * poll group. This can collectively wait for interrupt events on all those file descriptors.
3034 : *
3035 : * the disconnected_qpair_cb will be called for all disconnected qpairs in the poll group
3036 : * including qpairs which fail within the context of this call.
3037 : * The user is responsible for trying to reconnect or destroy those qpairs.
3038 : *
3039 : * \param group The poll group on which to wait for interrupt events.
3040 : * \param disconnected_qpair_cb A callback function of type spdk_nvme_disconnected_qpair_cb. Must
3041 : * be non-NULL.
3042 : *
3043 : * \return number of events processed on success, -EINVAL if no disconnected_qpair_cb is passed, or
3044 : * -errno in case of failure.
3045 : */
3046 : int spdk_nvme_poll_group_wait(struct spdk_nvme_poll_group *group,
3047 : spdk_nvme_disconnected_qpair_cb disconnected_qpair_cb);
3048 :
3049 : /**
3050 : * Return the internal epoll file descriptor of this poll group.
3051 : *
3052 : * \param group The poll group for which epoll fd is requested.
3053 : *
3054 : * \return epoll fd for the poll group, -EINVAL if there is no fd group for this poll group.
3055 : */
3056 : int spdk_nvme_poll_group_get_fd(struct spdk_nvme_poll_group *group);
3057 :
3058 : /**
3059 : * Destroy an empty poll group.
3060 : *
3061 : * \param group The group to destroy.
3062 : *
3063 : * return 0 on success, -EBUSY if the poll group is not empty.
3064 : */
3065 : int spdk_nvme_poll_group_destroy(struct spdk_nvme_poll_group *group);
3066 :
3067 : /**
3068 : * Poll for completions on all qpairs in this poll group.
3069 : *
3070 : * the disconnected_qpair_cb will be called for all disconnected qpairs in the poll group
3071 : * including qpairs which fail within the context of this call.
3072 : * The user is responsible for trying to reconnect or destroy those qpairs.
3073 : *
3074 : * \param group The group on which to poll for completions.
3075 : * \param completions_per_qpair The maximum number of completions per qpair.
3076 : * \param disconnected_qpair_cb A callback function of type spdk_nvme_disconnected_qpair_cb. Must be non-NULL.
3077 : *
3078 : * return The number of completions across all qpairs, -EINVAL if no disconnected_qpair_cb is passed, or
3079 : * -EIO if the shared completion queue cannot be polled for the RDMA transport.
3080 : */
3081 : int64_t spdk_nvme_poll_group_process_completions(struct spdk_nvme_poll_group *group,
3082 : uint32_t completions_per_qpair, spdk_nvme_disconnected_qpair_cb disconnected_qpair_cb);
3083 :
3084 : /**
3085 : * Check if all qpairs in the poll group are connected.
3086 : *
3087 : * This function allows the caller to check if all qpairs in a poll group are
3088 : * connected. This API is generally only suitable during application startup,
3089 : * to check when a large number of async connections have completed.
3090 : *
3091 : * It is useful for applications like benchmarking tools to create
3092 : * a large number of qpairs, but then ensuring they are all fully connected before
3093 : * proceeding with I/O.
3094 : *
3095 : * \param group The group on which to poll connecting qpairs.
3096 : *
3097 : * return 0 if all qpairs are in CONNECTED state, -EIO if any connections failed to connect, -EAGAIN if
3098 : * any qpairs are still trying to connected.
3099 : */
3100 : int spdk_nvme_poll_group_all_connected(struct spdk_nvme_poll_group *group);
3101 :
3102 : /**
3103 : * Retrieve the user context for this specific poll group.
3104 : *
3105 : * \param group The poll group from which to retrieve the context.
3106 : *
3107 : * \return A pointer to the user provided poll group context.
3108 : */
3109 : void *spdk_nvme_poll_group_get_ctx(struct spdk_nvme_poll_group *group);
3110 :
3111 : /**
3112 : * Retrieves transport statistics for the given poll group.
3113 : *
3114 : * Note: the structure returned by this function should later be freed with
3115 : * @b spdk_nvme_poll_group_free_stats function
3116 : *
3117 : * \param group Pointer to NVME poll group
3118 : * \param stats Double pointer to statistics to be filled by this function
3119 : * \return 0 on success or negated errno on failure
3120 : */
3121 : int spdk_nvme_poll_group_get_stats(struct spdk_nvme_poll_group *group,
3122 : struct spdk_nvme_poll_group_stat **stats);
3123 :
3124 : /**
3125 : * Frees poll group statistics retrieved using @b spdk_nvme_poll_group_get_stats function
3126 : *
3127 : * @param group Pointer to a poll group
3128 : * @param stat Pointer to statistics to be released
3129 : */
3130 : void spdk_nvme_poll_group_free_stats(struct spdk_nvme_poll_group *group,
3131 : struct spdk_nvme_poll_group_stat *stat);
3132 :
3133 : /**
3134 : * Get the identify namespace data as defined by the NVMe specification.
3135 : *
3136 : * This function is thread safe and can be called at any point while the controller
3137 : * is attached to the SPDK NVMe driver.
3138 : *
3139 : * \param ns Namespace.
3140 : *
3141 : * \return a pointer to the namespace data.
3142 : */
3143 : const struct spdk_nvme_ns_data *spdk_nvme_ns_get_data(struct spdk_nvme_ns *ns);
3144 :
3145 : /**
3146 : * Get the I/O command set specific identify namespace data for NVM command set
3147 : * as defined by the NVMe specification.
3148 : *
3149 : * This function is thread safe and can be called at any point while the controller
3150 : * is attached to the SPDK NVMe driver.
3151 : *
3152 : * \param ns Namespace.
3153 : *
3154 : * \return a pointer to the identify namespace data.
3155 : */
3156 : const struct spdk_nvme_nvm_ns_data *spdk_nvme_nvm_ns_get_data(struct spdk_nvme_ns *ns);
3157 :
3158 : /**
3159 : * Get the namespace id (index number) from the given namespace handle.
3160 : *
3161 : * This function is thread safe and can be called at any point while the controller
3162 : * is attached to the SPDK NVMe driver.
3163 : *
3164 : * \param ns Namespace.
3165 : *
3166 : * \return namespace id.
3167 : */
3168 : uint32_t spdk_nvme_ns_get_id(struct spdk_nvme_ns *ns);
3169 :
3170 : /**
3171 : * Get the controller with which this namespace is associated.
3172 : *
3173 : * This function is thread safe and can be called at any point while the controller
3174 : * is attached to the SPDK NVMe driver.
3175 : *
3176 : * \param ns Namespace.
3177 : *
3178 : * \return a pointer to the controller.
3179 : */
3180 : struct spdk_nvme_ctrlr *spdk_nvme_ns_get_ctrlr(struct spdk_nvme_ns *ns);
3181 :
3182 : /**
3183 : * Determine whether a namespace is active.
3184 : *
3185 : * Inactive namespaces cannot be the target of I/O commands.
3186 : *
3187 : * \param ns Namespace to query.
3188 : *
3189 : * \return true if active, or false if inactive.
3190 : */
3191 : bool spdk_nvme_ns_is_active(struct spdk_nvme_ns *ns);
3192 :
3193 : /**
3194 : * Get the maximum transfer size, in bytes, for an I/O sent to the given namespace.
3195 : *
3196 : * This function is thread safe and can be called at any point while the controller
3197 : * is attached to the SPDK NVMe driver.
3198 : *
3199 : * \param ns Namespace to query.
3200 : *
3201 : * \return the maximum transfer size in bytes.
3202 : */
3203 : uint32_t spdk_nvme_ns_get_max_io_xfer_size(struct spdk_nvme_ns *ns);
3204 :
3205 : /**
3206 : * Get the sector size, in bytes, of the given namespace.
3207 : *
3208 : * This function returns the size of the data sector only. It does not
3209 : * include metadata size.
3210 : *
3211 : * This function is thread safe and can be called at any point while the controller
3212 : * is attached to the SPDK NVMe driver.
3213 : *
3214 : * \param ns Namespace to query.
3215 : *
3216 : * /return the sector size in bytes.
3217 : */
3218 : uint32_t spdk_nvme_ns_get_sector_size(struct spdk_nvme_ns *ns);
3219 :
3220 : /**
3221 : * Get the extended sector size, in bytes, of the given namespace.
3222 : *
3223 : * This function returns the size of the data sector plus metadata.
3224 : *
3225 : * This function is thread safe and can be called at any point while the controller
3226 : * is attached to the SPDK NVMe driver.
3227 : *
3228 : * \param ns Namespace to query.
3229 : *
3230 : * /return the extended sector size in bytes.
3231 : */
3232 : uint32_t spdk_nvme_ns_get_extended_sector_size(struct spdk_nvme_ns *ns);
3233 :
3234 : /**
3235 : * Get the number of sectors for the given namespace.
3236 : *
3237 : * This function is thread safe and can be called at any point while the controller
3238 : * is attached to the SPDK NVMe driver.
3239 : *
3240 : * \param ns Namespace to query.
3241 : *
3242 : * \return the number of sectors.
3243 : */
3244 : uint64_t spdk_nvme_ns_get_num_sectors(struct spdk_nvme_ns *ns);
3245 :
3246 : /**
3247 : * Get the size, in bytes, of the given namespace.
3248 : *
3249 : * This function is thread safe and can be called at any point while the controller
3250 : * is attached to the SPDK NVMe driver.
3251 : *
3252 : * \param ns Namespace to query.
3253 : *
3254 : * \return the size of the given namespace in bytes.
3255 : */
3256 : uint64_t spdk_nvme_ns_get_size(struct spdk_nvme_ns *ns);
3257 :
3258 : /**
3259 : * Get the end-to-end data protection information type of the given namespace.
3260 : *
3261 : * This function is thread safe and can be called at any point while the controller
3262 : * is attached to the SPDK NVMe driver.
3263 : *
3264 : * \param ns Namespace to query.
3265 : *
3266 : * \return the end-to-end data protection information type.
3267 : */
3268 : enum spdk_nvme_pi_type spdk_nvme_ns_get_pi_type(struct spdk_nvme_ns *ns);
3269 :
3270 : /**
3271 : * Get the end-to-end data protection information format of the given namespace.
3272 : *
3273 : * This function is thread safe and can be called at any point while the controller
3274 : * is attached to the SPDK NVMe driver.
3275 : *
3276 : * \param ns Namespace to query.
3277 : *
3278 : * \return the end-to-end data protection information format.
3279 : */
3280 : enum spdk_nvme_pi_format spdk_nvme_ns_get_pi_format(struct spdk_nvme_ns *ns);
3281 :
3282 : /**
3283 : * Get the metadata size, in bytes, of the given namespace.
3284 : *
3285 : * This function is thread safe and can be called at any point while the controller
3286 : * is attached to the SPDK NVMe driver.
3287 : *
3288 : * \param ns Namespace to query.
3289 : *
3290 : * \return the metadata size of the given namespace in bytes.
3291 : */
3292 : uint32_t spdk_nvme_ns_get_md_size(struct spdk_nvme_ns *ns);
3293 :
3294 : /**
3295 : * Get the format index of the given namespace.
3296 : *
3297 : * This function is thread safe and can be called at any point while the controller
3298 : * is attached to the SPDK NVMe driver.
3299 : *
3300 : * \param nsdata pointer to the NVMe namespace data.
3301 : *
3302 : * \return the format index of the given namespace.
3303 : */
3304 : uint32_t spdk_nvme_ns_get_format_index(const struct spdk_nvme_ns_data *nsdata);
3305 :
3306 : /**
3307 : * Check whether if the namespace can support extended LBA when end-to-end data
3308 : * protection enabled.
3309 : *
3310 : * This function is thread safe and can be called at any point while the controller
3311 : * is attached to the SPDK NVMe driver.
3312 : *
3313 : * \param ns Namespace to query.
3314 : *
3315 : * \return true if the namespace can support extended LBA when end-to-end data
3316 : * protection enabled, or false otherwise.
3317 : */
3318 : bool spdk_nvme_ns_supports_extended_lba(struct spdk_nvme_ns *ns);
3319 :
3320 : /**
3321 : * Check whether if the namespace supports compare operation
3322 : *
3323 : * This function is thread safe and can be called at any point while the controller
3324 : * is attached to the SPDK NVMe driver.
3325 : *
3326 : * \param ns Namespace to query.
3327 : *
3328 : * \return true if the namespace supports compare operation, or false otherwise.
3329 : */
3330 : bool spdk_nvme_ns_supports_compare(struct spdk_nvme_ns *ns);
3331 :
3332 : /**
3333 : * Determine the value returned when reading deallocated blocks.
3334 : *
3335 : * If deallocated blocks return 0, the deallocate command can be used as a more
3336 : * efficient alternative to the write_zeroes command, especially for large requests.
3337 : *
3338 : * \param ns Namespace.
3339 : *
3340 : * \return the logical block read value.
3341 : */
3342 : enum spdk_nvme_dealloc_logical_block_read_value spdk_nvme_ns_get_dealloc_logical_block_read_value(
3343 : struct spdk_nvme_ns *ns);
3344 :
3345 : /**
3346 : * Get the optimal I/O boundary, in blocks, for the given namespace.
3347 : *
3348 : * Read and write commands should not cross the optimal I/O boundary for best
3349 : * performance.
3350 : *
3351 : * \param ns Namespace to query.
3352 : *
3353 : * \return Optimal granularity of I/O commands, in blocks, or 0 if no optimal
3354 : * granularity is reported.
3355 : */
3356 : uint32_t spdk_nvme_ns_get_optimal_io_boundary(struct spdk_nvme_ns *ns);
3357 :
3358 : /**
3359 : * Get the NGUID for the given namespace.
3360 : *
3361 : * \param ns Namespace to query.
3362 : *
3363 : * \return a pointer to namespace NGUID, or NULL if ns does not have a NGUID.
3364 : */
3365 : const uint8_t *spdk_nvme_ns_get_nguid(const struct spdk_nvme_ns *ns);
3366 :
3367 : /**
3368 : * Get the UUID for the given namespace.
3369 : *
3370 : * \param ns Namespace to query.
3371 : *
3372 : * \return a pointer to namespace UUID, or NULL if ns does not have a UUID.
3373 : */
3374 : const struct spdk_uuid *spdk_nvme_ns_get_uuid(const struct spdk_nvme_ns *ns);
3375 :
3376 : /**
3377 : * Get the Command Set Identifier for the given namespace.
3378 : *
3379 : * \param ns Namespace to query.
3380 : *
3381 : * \return the namespace Command Set Identifier.
3382 : */
3383 : enum spdk_nvme_csi spdk_nvme_ns_get_csi(const struct spdk_nvme_ns *ns);
3384 :
3385 : /**
3386 : * \brief Namespace command support flags.
3387 : */
3388 : enum spdk_nvme_ns_flags {
3389 : SPDK_NVME_NS_DEALLOCATE_SUPPORTED = 1 << 0, /**< The deallocate command is supported */
3390 : SPDK_NVME_NS_FLUSH_SUPPORTED = 1 << 1, /**< The flush command is supported */
3391 : SPDK_NVME_NS_RESERVATION_SUPPORTED = 1 << 2, /**< The reservation command is supported */
3392 : SPDK_NVME_NS_WRITE_ZEROES_SUPPORTED = 1 << 3, /**< The write zeroes command is supported */
3393 : SPDK_NVME_NS_DPS_PI_SUPPORTED = 1 << 4, /**< The end-to-end data protection is supported */
3394 : SPDK_NVME_NS_EXTENDED_LBA_SUPPORTED = 1 << 5, /**< The extended lba format is supported,
3395 : metadata is transferred as a contiguous
3396 : part of the logical block that it is associated with */
3397 : SPDK_NVME_NS_WRITE_UNCORRECTABLE_SUPPORTED = 1 << 6, /**< The write uncorrectable command is supported */
3398 : SPDK_NVME_NS_COMPARE_SUPPORTED = 1 << 7, /**< The compare command is supported */
3399 : };
3400 :
3401 : /**
3402 : * Get the flags for the given namespace.
3403 : *
3404 : * See spdk_nvme_ns_flags for the possible flags returned.
3405 : *
3406 : * This function is thread safe and can be called at any point while the controller
3407 : * is attached to the SPDK NVMe driver.
3408 : *
3409 : * \param ns Namespace to query.
3410 : *
3411 : * \return the flags for the given namespace.
3412 : */
3413 : uint32_t spdk_nvme_ns_get_flags(struct spdk_nvme_ns *ns);
3414 :
3415 : /**
3416 : * Get the ANA group ID for the given namespace.
3417 : *
3418 : * This function should be called only if spdk_nvme_ctrlr_is_log_page_supported() returns
3419 : * true for the controller and log page ID SPDK_NVME_LOG_ASYMMETRIC_NAMESPACE_ACCESS.
3420 : *
3421 : * This function is thread safe and can be called at any point while the controller
3422 : * is attached to the SPDK NVMe driver.
3423 : *
3424 : * \param ns Namespace to query.
3425 : *
3426 : * \return the ANA group ID for the given namespace.
3427 : */
3428 : uint32_t spdk_nvme_ns_get_ana_group_id(const struct spdk_nvme_ns *ns);
3429 :
3430 : /**
3431 : * Get the ANA state for the given namespace.
3432 : *
3433 : * This function should be called only if spdk_nvme_ctrlr_is_log_page_supported() returns
3434 : * true for the controller and log page ID SPDK_NVME_LOG_ASYMMETRIC_NAMESPACE_ACCESS.
3435 : *
3436 : * This function is thread safe and can be called at any point while the controller
3437 : * is attached to the SPDK NVMe driver.
3438 : *
3439 : * \param ns Namespace to query.
3440 : *
3441 : * \return the ANA state for the given namespace.
3442 : */
3443 : enum spdk_nvme_ana_state spdk_nvme_ns_get_ana_state(const struct spdk_nvme_ns *ns);
3444 :
3445 : /**
3446 : * Submit a write I/O to the specified NVMe namespace.
3447 : *
3448 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3449 : * The user must ensure that only one thread submits I/O on a given qpair at any
3450 : * given time.
3451 : *
3452 : * \param ns NVMe namespace to submit the write I/O.
3453 : * \param qpair I/O queue pair to submit the request.
3454 : * \param payload Virtual address pointer to the data payload.
3455 : * \param lba Starting LBA to write the data.
3456 : * \param lba_count Length (in sectors) for the write operation.
3457 : * \param cb_fn Callback function to invoke when the I/O is completed.
3458 : * \param cb_arg Argument to pass to the callback function.
3459 : * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
3460 : * spdk/nvme_spec.h, for this I/O.
3461 : *
3462 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3463 : * -EINVAL: The request is malformed.
3464 : * -ENOMEM: The request cannot be allocated.
3465 : * -ENXIO: The qpair is failed at the transport level.
3466 : */
3467 : int spdk_nvme_ns_cmd_write(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
3468 : uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
3469 : void *cb_arg, uint32_t io_flags);
3470 :
3471 : /**
3472 : * Submit a write I/O to the specified NVMe namespace.
3473 : *
3474 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3475 : * The user must ensure that only one thread submits I/O on a given qpair at any
3476 : * given time.
3477 : *
3478 : * \param ns NVMe namespace to submit the write I/O.
3479 : * \param qpair I/O queue pair to submit the request.
3480 : * \param lba Starting LBA to write the data.
3481 : * \param lba_count Length (in sectors) for the write operation.
3482 : * \param cb_fn Callback function to invoke when the I/O is completed.
3483 : * \param cb_arg Argument to pass to the callback function.
3484 : * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
3485 : * \param reset_sgl_fn Callback function to reset scattered payload.
3486 : * \param next_sge_fn Callback function to iterate each scattered payload memory
3487 : * segment.
3488 : *
3489 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3490 : * -EINVAL: The request is malformed.
3491 : * -ENOMEM: The request cannot be allocated.
3492 : * -ENXIO: The qpair is failed at the transport level.
3493 : */
3494 : int spdk_nvme_ns_cmd_writev(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3495 : uint64_t lba, uint32_t lba_count,
3496 : spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
3497 : spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
3498 : spdk_nvme_req_next_sge_cb next_sge_fn);
3499 :
3500 : /**
3501 : * Submit a write I/O to the specified NVMe namespace.
3502 : *
3503 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3504 : * The user must ensure that only one thread submits I/O on a given qpair at any
3505 : * given time.
3506 : *
3507 : * \param ns NVMe namespace to submit the write I/O
3508 : * \param qpair I/O queue pair to submit the request
3509 : * \param lba starting LBA to write the data
3510 : * \param lba_count length (in sectors) for the write operation
3511 : * \param cb_fn callback function to invoke when the I/O is completed
3512 : * \param cb_arg argument to pass to the callback function
3513 : * \param io_flags set flags, defined in nvme_spec.h, for this I/O
3514 : * \param reset_sgl_fn callback function to reset scattered payload
3515 : * \param next_sge_fn callback function to iterate each scattered
3516 : * payload memory segment
3517 : * \param metadata virtual address pointer to the metadata payload, the length
3518 : * of metadata is specified by spdk_nvme_ns_get_md_size()
3519 : * \param apptag_mask application tag mask.
3520 : * \param apptag application tag to use end-to-end protection information.
3521 : *
3522 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3523 : * -EINVAL: The request is malformed.
3524 : * -ENOMEM: The request cannot be allocated.
3525 : * -ENXIO: The qpair is failed at the transport level.
3526 : */
3527 : int spdk_nvme_ns_cmd_writev_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3528 : uint64_t lba, uint32_t lba_count,
3529 : spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
3530 : spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
3531 : spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata,
3532 : uint16_t apptag_mask, uint16_t apptag);
3533 :
3534 : /**
3535 : * Submit a write I/O to the specified NVMe namespace.
3536 : *
3537 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3538 : * The user must ensure that only one thread submits I/O on a given qpair at any
3539 : * given time.
3540 : *
3541 : * \param ns NVMe namespace to submit the write I/O
3542 : * \param qpair I/O queue pair to submit the request
3543 : * \param lba starting LBA to write the data
3544 : * \param lba_count length (in sectors) for the write operation
3545 : * \param cb_fn callback function to invoke when the I/O is completed
3546 : * \param cb_arg argument to pass to the callback function
3547 : * \param reset_sgl_fn callback function to reset scattered payload
3548 : * \param next_sge_fn callback function to iterate each scattered
3549 : * payload memory segment
3550 : * \param opts Optional structure with extended IO request options. If provided, the caller must
3551 : * guarantee that this structure is accessible until IO completes
3552 : *
3553 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3554 : * -EINVAL: The request is malformed.
3555 : * -ENOMEM: The request cannot be allocated.
3556 : * -ENXIO: The qpair is failed at the transport level.
3557 : * -EFAULT: Invalid address was specified as part of payload. cb_fn is also called
3558 : * with error status including dnr=1 in this case.
3559 : */
3560 : int spdk_nvme_ns_cmd_writev_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3561 : uint64_t lba, uint32_t lba_count,
3562 : spdk_nvme_cmd_cb cb_fn, void *cb_arg,
3563 : spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
3564 : spdk_nvme_req_next_sge_cb next_sge_fn,
3565 : struct spdk_nvme_ns_cmd_ext_io_opts *opts);
3566 :
3567 : /**
3568 : * Submit a write I/O to the specified NVMe namespace.
3569 : *
3570 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3571 : * The user must ensure that only one thread submits I/O on a given qpair at any
3572 : * given time.
3573 : *
3574 : * \param ns NVMe namespace to submit the write I/O
3575 : * \param qpair I/O queue pair to submit the request
3576 : * \param payload Virtual address pointer to the data payload.
3577 : * \param lba starting LBA to write the data
3578 : * \param lba_count length (in sectors) for the write operation
3579 : * \param cb_fn callback function to invoke when the I/O is completed
3580 : * \param cb_arg argument to pass to the callback function
3581 : * \param opts Optional structure with extended IO request options. If provided, the caller must
3582 : * guarantee that this structure is accessible until IO completes
3583 : *
3584 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3585 : * -EINVAL: The request is malformed.
3586 : * -ENOMEM: The request cannot be allocated.
3587 : * -ENXIO: The qpair is failed at the transport level.
3588 : * -EFAULT: Invalid address was specified as part of payload. cb_fn is also called
3589 : * with error status including dnr=1 in this case.
3590 : */
3591 : int spdk_nvme_ns_cmd_write_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3592 : void *payload, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg,
3593 : struct spdk_nvme_ns_cmd_ext_io_opts *opts);
3594 :
3595 : /**
3596 : * Submit a write I/O to the specified NVMe namespace.
3597 : *
3598 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3599 : * The user must ensure that only one thread submits I/O on a given qpair at any
3600 : * given time.
3601 : *
3602 : * \param ns NVMe namespace to submit the write I/O.
3603 : * \param qpair I/O queue pair to submit the request.
3604 : * \param payload Virtual address pointer to the data payload.
3605 : * \param metadata Virtual address pointer to the metadata payload, the length
3606 : * of metadata is specified by spdk_nvme_ns_get_md_size().
3607 : * \param lba Starting LBA to write the data.
3608 : * \param lba_count Length (in sectors) for the write operation.
3609 : * \param cb_fn Callback function to invoke when the I/O is completed.
3610 : * \param cb_arg Argument to pass to the callback function.
3611 : * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
3612 : * spdk/nvme_spec.h, for this I/O.
3613 : * \param apptag_mask Application tag mask.
3614 : * \param apptag Application tag to use end-to-end protection information.
3615 : *
3616 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3617 : * -EINVAL: The request is malformed.
3618 : * -ENOMEM: The request cannot be allocated.
3619 : * -ENXIO: The qpair is failed at the transport level.
3620 : */
3621 : int spdk_nvme_ns_cmd_write_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3622 : void *payload, void *metadata,
3623 : uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
3624 : void *cb_arg, uint32_t io_flags,
3625 : uint16_t apptag_mask, uint16_t apptag);
3626 :
3627 : /**
3628 : * Submit a write zeroes I/O to the specified NVMe namespace.
3629 : *
3630 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3631 : * The user must ensure that only one thread submits I/O on a given qpair at any
3632 : * given time.
3633 : *
3634 : * \param ns NVMe namespace to submit the write zeroes I/O.
3635 : * \param qpair I/O queue pair to submit the request.
3636 : * \param lba Starting LBA for this command.
3637 : * \param lba_count Length (in sectors) for the write zero operation.
3638 : * \param cb_fn Callback function to invoke when the I/O is completed.
3639 : * \param cb_arg Argument to pass to the callback function.
3640 : * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
3641 : * spdk/nvme_spec.h, for this I/O.
3642 : *
3643 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3644 : * -EINVAL: The request is malformed.
3645 : * -ENOMEM: The request cannot be allocated.
3646 : * -ENXIO: The qpair is failed at the transport level.
3647 : */
3648 : int spdk_nvme_ns_cmd_write_zeroes(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3649 : uint64_t lba, uint32_t lba_count,
3650 : spdk_nvme_cmd_cb cb_fn, void *cb_arg,
3651 : uint32_t io_flags);
3652 :
3653 : /**
3654 : * Submit a verify I/O to the specified NVMe namespace.
3655 : *
3656 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3657 : * The user must ensure that only one thread submits I/O on a given qpair at any
3658 : * given time.
3659 : *
3660 : * \param ns NVMe namespace to submit the verify I/O.
3661 : * \param qpair I/O queue pair to submit the request.
3662 : * \param lba Starting LBA to verify the data.
3663 : * \param lba_count Length (in sectors) for the verify operation.
3664 : * \param cb_fn Callback function to invoke when the I/O is completed.
3665 : * \param cb_arg Argument to pass to the callback function.
3666 : * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in
3667 : * spdk/nvme_spec.h, for this I/O.
3668 : *
3669 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3670 : * -EINVAL: The request is malformed.
3671 : * -ENOMEM: The request cannot be allocated.
3672 : * -ENXIO: The qpair is failed at the transport level.
3673 : */
3674 : int spdk_nvme_ns_cmd_verify(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3675 : uint64_t lba, uint32_t lba_count,
3676 : spdk_nvme_cmd_cb cb_fn, void *cb_arg,
3677 : uint32_t io_flags);
3678 :
3679 : /**
3680 : * Submit a write uncorrectable I/O to the specified NVMe namespace.
3681 : *
3682 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3683 : * The user must ensure that only one thread submits I/O on a given qpair at any
3684 : * given time.
3685 : *
3686 : * \param ns NVMe namespace to submit the write uncorrectable I/O.
3687 : * \param qpair I/O queue pair to submit the request.
3688 : * \param lba Starting LBA for this command.
3689 : * \param lba_count Length (in sectors) for the write uncorrectable operation.
3690 : * \param cb_fn Callback function to invoke when the I/O is completed.
3691 : * \param cb_arg Argument to pass to the callback function.
3692 : *
3693 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3694 : * -EINVAL: The request is malformed.
3695 : * -ENOMEM: The request cannot be allocated.
3696 : * -ENXIO: The qpair is failed at the transport level.
3697 : */
3698 : int spdk_nvme_ns_cmd_write_uncorrectable(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3699 : uint64_t lba, uint32_t lba_count,
3700 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
3701 :
3702 : /**
3703 : * \brief Submits a read I/O to the specified NVMe namespace.
3704 : *
3705 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3706 : * The user must ensure that only one thread submits I/O on a given qpair at any
3707 : * given time.
3708 : *
3709 : * \param ns NVMe namespace to submit the read I/O.
3710 : * \param qpair I/O queue pair to submit the request.
3711 : * \param payload Virtual address pointer to the data payload.
3712 : * \param lba Starting LBA to read the data.
3713 : * \param lba_count Length (in sectors) for the read operation.
3714 : * \param cb_fn Callback function to invoke when the I/O is completed.
3715 : * \param cb_arg Argument to pass to the callback function.
3716 : * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
3717 : *
3718 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3719 : * -EINVAL: The request is malformed.
3720 : * -ENOMEM: The request cannot be allocated.
3721 : * -ENXIO: The qpair is failed at the transport level.
3722 : */
3723 : int spdk_nvme_ns_cmd_read(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
3724 : uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
3725 : void *cb_arg, uint32_t io_flags);
3726 :
3727 : /**
3728 : * Submit a read I/O to the specified NVMe namespace.
3729 : *
3730 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3731 : * The user must ensure that only one thread submits I/O on a given qpair at any
3732 : * given time.
3733 : *
3734 : * \param ns NVMe namespace to submit the read I/O.
3735 : * \param qpair I/O queue pair to submit the request.
3736 : * \param lba Starting LBA to read the data.
3737 : * \param lba_count Length (in sectors) for the read operation.
3738 : * \param cb_fn Callback function to invoke when the I/O is completed.
3739 : * \param cb_arg Argument to pass to the callback function.
3740 : * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
3741 : * \param reset_sgl_fn Callback function to reset scattered payload.
3742 : * \param next_sge_fn Callback function to iterate each scattered payload memory
3743 : * segment.
3744 : *
3745 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3746 : * -EINVAL: The request is malformed.
3747 : * -ENOMEM: The request cannot be allocated.
3748 : * -ENXIO: The qpair is failed at the transport level.
3749 : */
3750 : int spdk_nvme_ns_cmd_readv(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3751 : uint64_t lba, uint32_t lba_count,
3752 : spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
3753 : spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
3754 : spdk_nvme_req_next_sge_cb next_sge_fn);
3755 :
3756 : /**
3757 : * Submit a read I/O to the specified NVMe namespace.
3758 : *
3759 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3760 : * The user must ensure that only one thread submits I/O on a given qpair at any given time.
3761 : *
3762 : * \param ns NVMe namespace to submit the read I/O
3763 : * \param qpair I/O queue pair to submit the request
3764 : * \param lba starting LBA to read the data
3765 : * \param lba_count length (in sectors) for the read operation
3766 : * \param cb_fn callback function to invoke when the I/O is completed
3767 : * \param cb_arg argument to pass to the callback function
3768 : * \param io_flags set flags, defined in nvme_spec.h, for this I/O
3769 : * \param reset_sgl_fn callback function to reset scattered payload
3770 : * \param next_sge_fn callback function to iterate each scattered
3771 : * payload memory segment
3772 : * \param metadata virtual address pointer to the metadata payload, the length
3773 : * of metadata is specified by spdk_nvme_ns_get_md_size()
3774 : * \param apptag_mask application tag mask.
3775 : * \param apptag application tag to use end-to-end protection information.
3776 : *
3777 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3778 : * -EINVAL: The request is malformed.
3779 : * -ENOMEM: The request cannot be allocated.
3780 : * -ENXIO: The qpair is failed at the transport level.
3781 : */
3782 : int spdk_nvme_ns_cmd_readv_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3783 : uint64_t lba, uint32_t lba_count,
3784 : spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
3785 : spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
3786 : spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata,
3787 : uint16_t apptag_mask, uint16_t apptag);
3788 :
3789 : /**
3790 : * Submit a read I/O to the specified NVMe namespace.
3791 : *
3792 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3793 : * The user must ensure that only one thread submits I/O on a given qpair at any given time.
3794 : *
3795 : * \param ns NVMe namespace to submit the read I/O
3796 : * \param qpair I/O queue pair to submit the request
3797 : * \param lba starting LBA to read the data
3798 : * \param lba_count length (in sectors) for the read operation
3799 : * \param cb_fn callback function to invoke when the I/O is completed
3800 : * \param cb_arg argument to pass to the callback function
3801 : * \param reset_sgl_fn callback function to reset scattered payload
3802 : * \param next_sge_fn callback function to iterate each scattered
3803 : * payload memory segment
3804 : * \param opts Optional structure with extended IO request options. If provided, the caller must
3805 : * guarantee that this structure is accessible until IO completes
3806 : *
3807 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3808 : * -EINVAL: The request is malformed.
3809 : * -ENOMEM: The request cannot be allocated.
3810 : * -ENXIO: The qpair is failed at the transport level.
3811 : * -EFAULT: Invalid address was specified as part of payload. cb_fn is also called
3812 : * with error status including dnr=1 in this case.
3813 : */
3814 : int spdk_nvme_ns_cmd_readv_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3815 : uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
3816 : void *cb_arg, spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
3817 : spdk_nvme_req_next_sge_cb next_sge_fn,
3818 : struct spdk_nvme_ns_cmd_ext_io_opts *opts);
3819 :
3820 : /**
3821 : * Submit a read I/O to the specified NVMe namespace.
3822 : *
3823 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3824 : * The user must ensure that only one thread submits I/O on a given qpair at any given time.
3825 : *
3826 : * \param ns NVMe namespace to submit the read I/O
3827 : * \param qpair I/O queue pair to submit the request
3828 : * \param payload virtual address pointer to the data payload
3829 : * \param lba starting LBA to read the data
3830 : * \param lba_count length (in sectors) for the read operation
3831 : * \param cb_fn callback function to invoke when the I/O is completed
3832 : * \param cb_arg argument to pass to the callback function
3833 : * \param opts Optional structure with extended IO request options. If provided, the caller must
3834 : * guarantee that this structure is accessible until IO completes
3835 : *
3836 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3837 : * -EINVAL: The request is malformed.
3838 : * -ENOMEM: The request cannot be allocated.
3839 : * -ENXIO: The qpair is failed at the transport level.
3840 : * -EFAULT: Invalid address was specified as part of payload. cb_fn is also called
3841 : * with error status including dnr=1 in this case.
3842 : */
3843 : int spdk_nvme_ns_cmd_read_ext(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
3844 : uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg,
3845 : struct spdk_nvme_ns_cmd_ext_io_opts *opts);
3846 :
3847 : /**
3848 : * Submits a read I/O to the specified NVMe namespace.
3849 : *
3850 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3851 : * The user must ensure that only one thread submits I/O on a given qpair at any
3852 : * given time.
3853 : *
3854 : * \param ns NVMe namespace to submit the read I/O
3855 : * \param qpair I/O queue pair to submit the request
3856 : * \param payload virtual address pointer to the data payload
3857 : * \param metadata virtual address pointer to the metadata payload, the length
3858 : * of metadata is specified by spdk_nvme_ns_get_md_size().
3859 : * \param lba starting LBA to read the data.
3860 : * \param lba_count Length (in sectors) for the read operation.
3861 : * \param cb_fn Callback function to invoke when the I/O is completed.
3862 : * \param cb_arg Argument to pass to the callback function.
3863 : * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
3864 : * \param apptag_mask Application tag mask.
3865 : * \param apptag Application tag to use end-to-end protection information.
3866 : *
3867 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3868 : * -EINVAL: The request is malformed.
3869 : * -ENOMEM: The request cannot be allocated.
3870 : * -ENXIO: The qpair is failed at the transport level.
3871 : */
3872 : int spdk_nvme_ns_cmd_read_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3873 : void *payload, void *metadata,
3874 : uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
3875 : void *cb_arg, uint32_t io_flags,
3876 : uint16_t apptag_mask, uint16_t apptag);
3877 :
3878 : /**
3879 : * Submit a data set management request to the specified NVMe namespace.
3880 : *
3881 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3882 : * The user must ensure that only one thread submits I/O on a given qpair at any
3883 : * given time.
3884 : *
3885 : * This is a convenience wrapper that will automatically allocate and construct
3886 : * the correct data buffers. Therefore, ranges does not need to be allocated from
3887 : * pinned memory and can be placed on the stack. If a higher performance, zero-copy
3888 : * version of DSM is required, simply build and submit a raw command using
3889 : * spdk_nvme_ctrlr_cmd_io_raw().
3890 : *
3891 : * \param ns NVMe namespace to submit the DSM request
3892 : * \param type A bit field constructed from \ref spdk_nvme_dsm_attribute.
3893 : * \param qpair I/O queue pair to submit the request
3894 : * \param ranges An array of \ref spdk_nvme_dsm_range elements describing the LBAs
3895 : * to operate on.
3896 : * \param num_ranges The number of elements in the ranges array.
3897 : * \param cb_fn Callback function to invoke when the I/O is completed
3898 : * \param cb_arg Argument to pass to the callback function
3899 : *
3900 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3901 : * -ENOMEM: The request cannot be allocated.
3902 : * -ENXIO: The qpair is failed at the transport level.
3903 : */
3904 : int spdk_nvme_ns_cmd_dataset_management(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3905 : uint32_t type,
3906 : const struct spdk_nvme_dsm_range *ranges,
3907 : uint16_t num_ranges,
3908 : spdk_nvme_cmd_cb cb_fn,
3909 : void *cb_arg);
3910 :
3911 : /**
3912 : * Submit a simple copy command request to the specified NVMe namespace.
3913 : *
3914 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3915 : * The user must ensure that only one thread submits I/O on a given qpair at any
3916 : * given time.
3917 : *
3918 : * This is a convenience wrapper that will automatically allocate and construct
3919 : * the correct data buffers. Therefore, ranges does not need to be allocated from
3920 : * pinned memory and can be placed on the stack. If a higher performance, zero-copy
3921 : * version of SCC is required, simply build and submit a raw command using
3922 : * spdk_nvme_ctrlr_cmd_io_raw().
3923 : *
3924 : * \param ns NVMe namespace to submit the SCC request
3925 : * \param qpair I/O queue pair to submit the request
3926 : * \param ranges An array of \ref spdk_nvme_scc_source_range elements describing the LBAs
3927 : * to operate on.
3928 : * \param num_ranges The number of elements in the ranges array.
3929 : * \param dest_lba Destination LBA to copy the data.
3930 : * \param cb_fn Callback function to invoke when the I/O is completed
3931 : * \param cb_arg Argument to pass to the callback function
3932 : *
3933 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3934 : * -ENOMEM: The request cannot be allocated.
3935 : * -EINVAL: Invalid ranges.
3936 : * -ENXIO: The qpair is failed at the transport level.
3937 : */
3938 : int spdk_nvme_ns_cmd_copy(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3939 : const struct spdk_nvme_scc_source_range *ranges,
3940 : uint16_t num_ranges,
3941 : uint64_t dest_lba,
3942 : spdk_nvme_cmd_cb cb_fn,
3943 : void *cb_arg);
3944 :
3945 : /**
3946 : * Submit a flush request to the specified NVMe namespace.
3947 : *
3948 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3949 : * The user must ensure that only one thread submits I/O on a given qpair at any
3950 : * given time.
3951 : *
3952 : * \param ns NVMe namespace to submit the flush request.
3953 : * \param qpair I/O queue pair to submit the request.
3954 : * \param cb_fn Callback function to invoke when the I/O is completed.
3955 : * \param cb_arg Argument to pass to the callback function.
3956 : *
3957 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3958 : * -ENOMEM: The request cannot be allocated.
3959 : * -ENXIO: The qpair is failed at the transport level.
3960 : */
3961 : int spdk_nvme_ns_cmd_flush(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
3962 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
3963 :
3964 : /**
3965 : * Submit a reservation register to the specified NVMe namespace.
3966 : *
3967 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3968 : * The user must ensure that only one thread submits I/O on a given qpair at any
3969 : * given time.
3970 : *
3971 : * \param ns NVMe namespace to submit the reservation register request.
3972 : * \param qpair I/O queue pair to submit the request.
3973 : * \param payload Virtual address pointer to the reservation register data.
3974 : * \param ignore_key '1' the current reservation key check is disabled.
3975 : * \param action Specifies the registration action.
3976 : * \param cptpl Change the Persist Through Power Loss state.
3977 : * \param cb_fn Callback function to invoke when the I/O is completed.
3978 : * \param cb_arg Argument to pass to the callback function.
3979 : *
3980 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
3981 : * -ENOMEM: The request cannot be allocated.
3982 : * -ENXIO: The qpair is failed at the transport level.
3983 : */
3984 : int spdk_nvme_ns_cmd_reservation_register(struct spdk_nvme_ns *ns,
3985 : struct spdk_nvme_qpair *qpair,
3986 : struct spdk_nvme_reservation_register_data *payload,
3987 : bool ignore_key,
3988 : enum spdk_nvme_reservation_register_action action,
3989 : enum spdk_nvme_reservation_register_cptpl cptpl,
3990 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
3991 :
3992 : /**
3993 : * Submits a reservation release to the specified NVMe namespace.
3994 : *
3995 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
3996 : * The user must ensure that only one thread submits I/O on a given qpair at any
3997 : * given time.
3998 : *
3999 : * \param ns NVMe namespace to submit the reservation release request.
4000 : * \param qpair I/O queue pair to submit the request.
4001 : * \param payload Virtual address pointer to current reservation key.
4002 : * \param ignore_key '1' the current reservation key check is disabled.
4003 : * \param action Specifies the reservation release action.
4004 : * \param type Reservation type for the namespace.
4005 : * \param cb_fn Callback function to invoke when the I/O is completed.
4006 : * \param cb_arg Argument to pass to the callback function.
4007 : *
4008 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
4009 : * -ENOMEM: The request cannot be allocated.
4010 : * -ENXIO: The qpair is failed at the transport level.
4011 : */
4012 : int spdk_nvme_ns_cmd_reservation_release(struct spdk_nvme_ns *ns,
4013 : struct spdk_nvme_qpair *qpair,
4014 : struct spdk_nvme_reservation_key_data *payload,
4015 : bool ignore_key,
4016 : enum spdk_nvme_reservation_release_action action,
4017 : enum spdk_nvme_reservation_type type,
4018 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
4019 :
4020 : /**
4021 : * Submits a reservation acquire to the specified NVMe namespace.
4022 : *
4023 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
4024 : * The user must ensure that only one thread submits I/O on a given qpair at any
4025 : * given time.
4026 : *
4027 : * \param ns NVMe namespace to submit the reservation acquire request.
4028 : * \param qpair I/O queue pair to submit the request.
4029 : * \param payload Virtual address pointer to reservation acquire data.
4030 : * \param ignore_key '1' the current reservation key check is disabled.
4031 : * \param action Specifies the reservation acquire action.
4032 : * \param type Reservation type for the namespace.
4033 : * \param cb_fn Callback function to invoke when the I/O is completed.
4034 : * \param cb_arg Argument to pass to the callback function.
4035 : *
4036 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
4037 : * -ENOMEM: The request cannot be allocated.
4038 : * -ENXIO: The qpair is failed at the transport level.
4039 : */
4040 : int spdk_nvme_ns_cmd_reservation_acquire(struct spdk_nvme_ns *ns,
4041 : struct spdk_nvme_qpair *qpair,
4042 : struct spdk_nvme_reservation_acquire_data *payload,
4043 : bool ignore_key,
4044 : enum spdk_nvme_reservation_acquire_action action,
4045 : enum spdk_nvme_reservation_type type,
4046 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
4047 :
4048 : /**
4049 : * Submit a reservation report to the specified NVMe namespace.
4050 : *
4051 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
4052 : * The user must ensure that only one thread submits I/O on a given qpair at any
4053 : * given time.
4054 : *
4055 : * \param ns NVMe namespace to submit the reservation report request.
4056 : * \param qpair I/O queue pair to submit the request.
4057 : * \param payload Virtual address pointer for reservation status data.
4058 : * \param len Length bytes for reservation status data structure.
4059 : * \param cb_fn Callback function to invoke when the I/O is completed.
4060 : * \param cb_arg Argument to pass to the callback function.
4061 : *
4062 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
4063 : * -ENOMEM: The request cannot be allocated.
4064 : * -ENXIO: The qpair is failed at the transport level.
4065 : */
4066 : int spdk_nvme_ns_cmd_reservation_report(struct spdk_nvme_ns *ns,
4067 : struct spdk_nvme_qpair *qpair,
4068 : void *payload, uint32_t len,
4069 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
4070 :
4071 : /**
4072 : * Submit an I/O management receive command to the specified NVMe namespace.
4073 : *
4074 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
4075 : * The user must ensure that only one thread submits I/O on a given qpair at any
4076 : * given time.
4077 : *
4078 : * \param ns NVMe namespace to submit the I/O mgmt receive request.
4079 : * \param qpair I/O queue pair to submit the request.
4080 : * \param payload Virtual address pointer for I/O mgmt receive data.
4081 : * \param len Length bytes for I/O mgmt receive data structure.
4082 : * \param mo Management operation to perform.
4083 : * \param mos Management operation specific field for the mo.
4084 : * \param cb_fn Callback function to invoke when the I/O is completed.
4085 : * \param cb_arg Argument to pass to the callback function.
4086 : *
4087 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
4088 : * -ENOMEM: The request cannot be allocated.
4089 : * -ENXIO: The qpair is failed at the transport level.
4090 : */
4091 : int spdk_nvme_ns_cmd_io_mgmt_recv(struct spdk_nvme_ns *ns,
4092 : struct spdk_nvme_qpair *qpair, void *payload,
4093 : uint32_t len, uint8_t mo, uint16_t mos,
4094 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
4095 :
4096 : /**
4097 : * Submit an I/O management send command to the specified NVMe namespace.
4098 : *
4099 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
4100 : * The user must ensure that only one thread submits I/O on a given qpair at any
4101 : * given time.
4102 : *
4103 : * \param ns NVMe namespace to submit the I/O mgmt send request.
4104 : * \param qpair I/O queue pair to submit the request.
4105 : * \param payload Virtual address pointer for I/O mgmt send data.
4106 : * \param len Length bytes for I/O mgmt send data structure.
4107 : * \param mo Management operation to perform.
4108 : * \param mos Management operation specific field for the mo.
4109 : * \param cb_fn Callback function to invoke when the I/O is completed.
4110 : * \param cb_arg Argument to pass to the callback function.
4111 : *
4112 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
4113 : * -ENOMEM: The request cannot be allocated.
4114 : * -ENXIO: The qpair is failed at the transport level.
4115 : */
4116 : int spdk_nvme_ns_cmd_io_mgmt_send(struct spdk_nvme_ns *ns,
4117 : struct spdk_nvme_qpair *qpair, void *payload,
4118 : uint32_t len, uint8_t mo, uint16_t mos,
4119 : spdk_nvme_cmd_cb cb_fn, void *cb_arg);
4120 :
4121 : /**
4122 : * Submit a compare I/O to the specified NVMe namespace.
4123 : *
4124 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
4125 : * The user must ensure that only one thread submits I/O on a given qpair at any
4126 : * given time.
4127 : *
4128 : * \param ns NVMe namespace to submit the compare I/O.
4129 : * \param qpair I/O queue pair to submit the request.
4130 : * \param payload Virtual address pointer to the data payload.
4131 : * \param lba Starting LBA to compare the data.
4132 : * \param lba_count Length (in sectors) for the compare operation.
4133 : * \param cb_fn Callback function to invoke when the I/O is completed.
4134 : * \param cb_arg Argument to pass to the callback function.
4135 : * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
4136 : *
4137 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
4138 : * -EINVAL: The request is malformed.
4139 : * -ENOMEM: The request cannot be allocated.
4140 : * -ENXIO: The qpair is failed at the transport level.
4141 : */
4142 : int spdk_nvme_ns_cmd_compare(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload,
4143 : uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
4144 : void *cb_arg, uint32_t io_flags);
4145 :
4146 : /**
4147 : * Submit a compare I/O to the specified NVMe namespace.
4148 : *
4149 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
4150 : * The user must ensure that only one thread submits I/O on a given qpair at any
4151 : * given time.
4152 : *
4153 : * \param ns NVMe namespace to submit the compare I/O.
4154 : * \param qpair I/O queue pair to submit the request.
4155 : * \param lba Starting LBA to compare the data.
4156 : * \param lba_count Length (in sectors) for the compare operation.
4157 : * \param cb_fn Callback function to invoke when the I/O is completed.
4158 : * \param cb_arg Argument to pass to the callback function.
4159 : * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
4160 : * \param reset_sgl_fn Callback function to reset scattered payload.
4161 : * \param next_sge_fn Callback function to iterate each scattered payload memory
4162 : * segment.
4163 : *
4164 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
4165 : * -EINVAL: The request is malformed.
4166 : * -ENOMEM: The request cannot be allocated.
4167 : * -ENXIO: The qpair is failed at the transport level.
4168 : */
4169 : int spdk_nvme_ns_cmd_comparev(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
4170 : uint64_t lba, uint32_t lba_count,
4171 : spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
4172 : spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
4173 : spdk_nvme_req_next_sge_cb next_sge_fn);
4174 :
4175 : /**
4176 : * Submit a compare I/O to the specified NVMe namespace.
4177 : *
4178 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
4179 : * The user must ensure that only one thread submits I/O on a given qpair at any
4180 : * given time.
4181 : *
4182 : * \param ns NVMe namespace to submit the compare I/O.
4183 : * \param qpair I/O queue pair to submit the request.
4184 : * \param lba Starting LBA to compare the data.
4185 : * \param lba_count Length (in sectors) for the compare operation.
4186 : * \param cb_fn Callback function to invoke when the I/O is completed.
4187 : * \param cb_arg Argument to pass to the callback function.
4188 : * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
4189 : * \param reset_sgl_fn Callback function to reset scattered payload.
4190 : * \param next_sge_fn Callback function to iterate each scattered payload memory
4191 : * segment.
4192 : * \param metadata Virtual address pointer to the metadata payload, the length
4193 : * of metadata is specified by spdk_nvme_ns_get_md_size()
4194 : * \param apptag_mask Application tag mask.
4195 : * \param apptag Application tag to use end-to-end protection information.
4196 : *
4197 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
4198 : * -EINVAL: The request is malformed.
4199 : * -ENOMEM: The request cannot be allocated.
4200 : * -ENXIO: The qpair is failed at the transport level.
4201 : */
4202 : int
4203 : spdk_nvme_ns_cmd_comparev_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
4204 : uint64_t lba, uint32_t lba_count,
4205 : spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags,
4206 : spdk_nvme_req_reset_sgl_cb reset_sgl_fn,
4207 : spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata,
4208 : uint16_t apptag_mask, uint16_t apptag);
4209 :
4210 : /**
4211 : * Submit a compare I/O to the specified NVMe namespace.
4212 : *
4213 : * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair().
4214 : * The user must ensure that only one thread submits I/O on a given qpair at any
4215 : * given time.
4216 : *
4217 : * \param ns NVMe namespace to submit the compare I/O.
4218 : * \param qpair I/O queue pair to submit the request.
4219 : * \param payload Virtual address pointer to the data payload.
4220 : * \param metadata Virtual address pointer to the metadata payload, the length
4221 : * of metadata is specified by spdk_nvme_ns_get_md_size().
4222 : * \param lba Starting LBA to compare the data.
4223 : * \param lba_count Length (in sectors) for the compare operation.
4224 : * \param cb_fn Callback function to invoke when the I/O is completed.
4225 : * \param cb_arg Argument to pass to the callback function.
4226 : * \param io_flags Set flags, defined in nvme_spec.h, for this I/O.
4227 : * \param apptag_mask Application tag mask.
4228 : * \param apptag Application tag to use end-to-end protection information.
4229 : *
4230 : * \return 0 if successfully submitted, negated errnos on the following error conditions:
4231 : * -EINVAL: The request is malformed.
4232 : * -ENOMEM: The request cannot be allocated.
4233 : * -ENXIO: The qpair is failed at the transport level.
4234 : */
4235 : int spdk_nvme_ns_cmd_compare_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair,
4236 : void *payload, void *metadata,
4237 : uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn,
4238 : void *cb_arg, uint32_t io_flags,
4239 : uint16_t apptag_mask, uint16_t apptag);
4240 :
4241 : /**
4242 : * \brief Inject an error for the next request with a given opcode.
4243 : *
4244 : * \param ctrlr NVMe controller.
4245 : * \param qpair I/O queue pair to add the error command,
4246 : * NULL for Admin queue pair.
4247 : * \param opc Opcode for Admin or I/O commands.
4248 : * \param do_not_submit True if matching requests should not be submitted
4249 : * to the controller, but instead completed manually
4250 : * after timeout_in_us has expired. False if matching
4251 : * requests should be submitted to the controller and
4252 : * have their completion status modified after the
4253 : * controller completes the request.
4254 : * \param timeout_in_us Wait specified microseconds when do_not_submit is true.
4255 : * \param err_count Number of matching requests to inject errors.
4256 : * \param sct Status code type.
4257 : * \param sc Status code.
4258 : *
4259 : * \return 0 if successfully enabled, ENOMEM if an error command
4260 : * structure cannot be allocated.
4261 : *
4262 : * The function can be called multiple times to inject errors for different
4263 : * commands. If the opcode matches an existing entry, the existing entry
4264 : * will be updated with the values specified.
4265 : */
4266 : int spdk_nvme_qpair_add_cmd_error_injection(struct spdk_nvme_ctrlr *ctrlr,
4267 : struct spdk_nvme_qpair *qpair,
4268 : uint8_t opc,
4269 : bool do_not_submit,
4270 : uint64_t timeout_in_us,
4271 : uint32_t err_count,
4272 : uint8_t sct, uint8_t sc);
4273 :
4274 : /**
4275 : * \brief Clear the specified NVMe command with error status.
4276 : *
4277 : * \param ctrlr NVMe controller.
4278 : * \param qpair I/O queue pair to remove the error command,
4279 : * \ NULL for Admin queue pair.
4280 : * \param opc Opcode for Admin or I/O commands.
4281 : *
4282 : * The function will remove specified command in the error list.
4283 : */
4284 : void spdk_nvme_qpair_remove_cmd_error_injection(struct spdk_nvme_ctrlr *ctrlr,
4285 : struct spdk_nvme_qpair *qpair,
4286 : uint8_t opc);
4287 :
4288 : /**
4289 : * \brief Given NVMe status, return ASCII string for that error.
4290 : *
4291 : * \param status Status from NVMe completion queue element.
4292 : * \return Returns status as an ASCII string.
4293 : */
4294 : const char *spdk_nvme_cpl_get_status_string(const struct spdk_nvme_status *status);
4295 :
4296 : /**
4297 : * \brief Given NVMe status, return ASCII string for the type of that error.
4298 : *
4299 : * \param status Status from NVMe completion queue element.
4300 : * \return Returns status type as an ASCII string.
4301 : */
4302 : const char *spdk_nvme_cpl_get_status_type_string(const struct spdk_nvme_status *status);
4303 :
4304 : /**
4305 : * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command).
4306 : *
4307 : * \param qpair Pointer to the NVMe queue pair - used to determine admin versus I/O queue.
4308 : * \param cmd Pointer to the submission queue command to be formatted.
4309 : */
4310 : void spdk_nvme_qpair_print_command(struct spdk_nvme_qpair *qpair,
4311 : struct spdk_nvme_cmd *cmd);
4312 :
4313 : /**
4314 : * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry.
4315 : *
4316 : * \param qpair Pointer to the NVMe queue pair - presently unused.
4317 : * \param cpl Pointer to the completion queue element to be formatted.
4318 : */
4319 : void spdk_nvme_qpair_print_completion(struct spdk_nvme_qpair *qpair,
4320 : struct spdk_nvme_cpl *cpl);
4321 :
4322 : /**
4323 : * \brief Gets the NVMe qpair ID for the specified qpair.
4324 : *
4325 : * \param qpair Pointer to the NVMe queue pair.
4326 : * \returns ID for the specified qpair.
4327 : */
4328 : uint16_t spdk_nvme_qpair_get_id(struct spdk_nvme_qpair *qpair);
4329 :
4330 : /**
4331 : * Gets the number of outstanding requests for the specified qpair.
4332 : *
4333 : * This number is not decremented until after a request's callback function is completed.
4334 : *
4335 : * This number is not matched necessarily to the number of NVMe commands submitted by the
4336 : * user. For example, nvme driver may split a request due to MDTS limitations, that will
4337 : * also allocate a request for the parent, etc.
4338 : *
4339 : * \param qpair Pointer to the NVMe queue pair.
4340 : * \returns number of outstanding requests for the specified qpair.
4341 : */
4342 : uint32_t spdk_nvme_qpair_get_num_outstanding_reqs(struct spdk_nvme_qpair *qpair);
4343 :
4344 : /**
4345 : * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command).
4346 : *
4347 : * \param qid Queue identifier.
4348 : * \param cmd Pointer to the submission queue command to be formatted.
4349 : */
4350 : void spdk_nvme_print_command(uint16_t qid, struct spdk_nvme_cmd *cmd);
4351 :
4352 : /**
4353 : * \brief Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry.
4354 : *
4355 : * \param qid Queue identifier.
4356 : * \param cpl Pointer to the completion queue element to be formatted.
4357 : */
4358 : void spdk_nvme_print_completion(uint16_t qid, struct spdk_nvme_cpl *cpl);
4359 :
4360 : /**
4361 : * Return the name of a digest.
4362 : *
4363 : * \param id Digest identifier (see `enum spdk_nvmf_dhchap_hash`).
4364 : *
4365 : * \return Name of the digest.
4366 : */
4367 : const char *spdk_nvme_dhchap_get_digest_name(int id);
4368 :
4369 : /**
4370 : * Return the id of a digest.
4371 : *
4372 : * \param name Name of a digest.
4373 : *
4374 : * \return Digest id (see `enum spdk_nvmf_dhchap_hash`) or negative errno on failure.
4375 : */
4376 : int spdk_nvme_dhchap_get_digest_id(const char *name);
4377 :
4378 : /**
4379 : * Return the length of a digest.
4380 : *
4381 : * \param id Digest identifier (see `enum spdk_nvmf_dhchap_hash`).
4382 : *
4383 : * \return Length of a digest or 0 if the id is unknown.
4384 : */
4385 : uint8_t spdk_nvme_dhchap_get_digest_length(int id);
4386 :
4387 : /**
4388 : * Return the name of a Diffie-Hellman group.
4389 : *
4390 : * \param id Diffie-Hellman group identifier (see `enum spdk_nvmf_dhchap_dhgroup`).
4391 : *
4392 : * \return Name of the Diffie-Hellman group.
4393 : */
4394 : const char *spdk_nvme_dhchap_get_dhgroup_name(int id);
4395 :
4396 : /**
4397 : * Return the id of a Diffie-Hellman group.
4398 : *
4399 : * \param name Name of a Diffie-Hellman group.
4400 : *
4401 : * \return Diffie-Hellman group id (see `enum spdk_nvmf_dhchap_dhgroup`) or negative errno
4402 : * on failure.
4403 : */
4404 : int spdk_nvme_dhchap_get_dhgroup_id(const char *name);
4405 :
4406 : struct ibv_context;
4407 : struct ibv_pd;
4408 : struct ibv_mr;
4409 :
4410 : /**
4411 : * RDMA Transport Hooks
4412 : */
4413 : struct spdk_nvme_rdma_hooks {
4414 : /**
4415 : * \brief Get an InfiniBand Verbs protection domain.
4416 : *
4417 : * \param trid the transport id
4418 : * \param verbs Infiniband verbs context
4419 : *
4420 : * \return pd of the nvme ctrlr
4421 : */
4422 : struct ibv_pd *(*get_ibv_pd)(const struct spdk_nvme_transport_id *trid,
4423 : struct ibv_context *verbs);
4424 :
4425 : /**
4426 : * \brief Get an InfiniBand Verbs memory region for a buffer.
4427 : *
4428 : * \param pd The protection domain returned from get_ibv_pd
4429 : * \param buf Memory buffer for which an rkey should be returned.
4430 : * \param size size of buf
4431 : *
4432 : * \return Infiniband remote key (rkey) for this buf
4433 : */
4434 : uint64_t (*get_rkey)(struct ibv_pd *pd, void *buf, size_t size);
4435 :
4436 : /**
4437 : * \brief Put back keys got from get_rkey.
4438 : *
4439 : * \param key The Infiniband remote key (rkey) got from get_rkey
4440 : *
4441 : */
4442 : void (*put_rkey)(uint64_t key);
4443 : };
4444 :
4445 : /**
4446 : * \brief Set the global hooks for the RDMA transport, if necessary.
4447 : *
4448 : * This call is optional and must be performed prior to probing for
4449 : * any devices. By default, the RDMA transport will use the ibverbs
4450 : * library to create protection domains and register memory. This
4451 : * is a mechanism to subvert that and use an existing registration.
4452 : *
4453 : * This function may only be called one time per process.
4454 : *
4455 : * \param hooks for initializing global hooks
4456 : */
4457 : void spdk_nvme_rdma_init_hooks(struct spdk_nvme_rdma_hooks *hooks);
4458 :
4459 : /**
4460 : * Get name of cuse device associated with NVMe controller.
4461 : *
4462 : * \param ctrlr Opaque handle to NVMe controller.
4463 : * \param name Buffer of be filled with cuse device name.
4464 : * \param size Size of name buffer.
4465 : *
4466 : * \return 0 on success. Negated errno on the following error conditions:
4467 : * -ENODEV: No cuse device registered for the controller.
4468 : * -ENSPC: Too small buffer size passed. Value of size pointer changed to the required length.
4469 : */
4470 : int spdk_nvme_cuse_get_ctrlr_name(struct spdk_nvme_ctrlr *ctrlr, char *name, size_t *size);
4471 :
4472 : /**
4473 : * Get name of cuse device associated with NVMe namespace.
4474 : *
4475 : * \param ctrlr Opaque handle to NVMe controller.
4476 : * \param nsid Namespace id.
4477 : * \param name Buffer of be filled with cuse device name.
4478 : * \param size Size of name buffer.
4479 : *
4480 : * \return 0 on success. Negated errno on the following error conditions:
4481 : * -ENODEV: No cuse device registered for the namespace.
4482 : * -ENSPC: Too small buffer size passed. Value of size pointer changed to the required length.
4483 : */
4484 : int spdk_nvme_cuse_get_ns_name(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid,
4485 : char *name, size_t *size);
4486 :
4487 : /**
4488 : * Create a character device at the path specified
4489 : *
4490 : * The character device can handle ioctls and is compatible with a standard
4491 : * Linux kernel NVMe device. Tools such as nvme-cli can be used to configure
4492 : * SPDK devices through this interface.
4493 : *
4494 : * The user is expected to be polling the admin qpair for this controller periodically
4495 : * for the CUSE device to function.
4496 : *
4497 : * \param ctrlr Opaque handle to the NVMe controller.
4498 : *
4499 : * \return 0 on success. Negated errno on failure.
4500 : */
4501 : int spdk_nvme_cuse_register(struct spdk_nvme_ctrlr *ctrlr);
4502 :
4503 : /**
4504 : * Remove a previously created character device
4505 : *
4506 : * \param ctrlr Opaque handle to the NVMe controller.
4507 : *
4508 : * \return 0 on success. Negated errno on failure.
4509 : */
4510 : int spdk_nvme_cuse_unregister(struct spdk_nvme_ctrlr *ctrlr);
4511 :
4512 : /**
4513 : * Get SPDK memory domains used by the given nvme controller.
4514 : *
4515 : * The user can call this function with \b domains set to NULL and \b array_size set to 0 to get the
4516 : * number of memory domains used by nvme controller
4517 : *
4518 : * \param ctrlr Opaque handle to the NVMe controller.
4519 : * \param domains Pointer to an array of memory domains to be filled by this function. The user should allocate big enough
4520 : * array to keep all memory domains used by nvme controller
4521 : * \param array_size size of \b domains array
4522 : * \return the number of entries in \b domains array or negated errno. If returned value is bigger than \b array_size passed by the user
4523 : * then the user should increase the size of \b domains array and call this function again. There is no guarantees that
4524 : * the content of \b domains array is valid in that case.
4525 : * -EINVAL if input parameters were invalid
4526 :
4527 : */
4528 : int spdk_nvme_ctrlr_get_memory_domains(const struct spdk_nvme_ctrlr *ctrlr,
4529 : struct spdk_memory_domain **domains, int array_size);
4530 :
4531 : /**
4532 : * Opaque handle for a transport poll group. Used by the transport function table.
4533 : */
4534 : struct spdk_nvme_transport_poll_group;
4535 :
4536 : /**
4537 : * Update and populate namespace CUSE devices (Experimental)
4538 : *
4539 : * \param ctrlr Opaque handle to the NVMe controller.
4540 : *
4541 : */
4542 : void spdk_nvme_cuse_update_namespaces(struct spdk_nvme_ctrlr *ctrlr);
4543 :
4544 : /**
4545 : * Signature for callback invoked after completing a register read/write operation.
4546 : *
4547 : * \param ctx Context passed by the user.
4548 : * \param value Value of the register, undefined in case of a failure.
4549 : * \param cpl Completion queue entry that contains the status of the command.
4550 : */
4551 : typedef void (*spdk_nvme_reg_cb)(void *ctx, uint64_t value, const struct spdk_nvme_cpl *cpl);
4552 :
4553 : struct nvme_request;
4554 :
4555 : struct spdk_nvme_transport;
4556 :
4557 : struct spdk_nvme_transport_ops {
4558 : char name[SPDK_NVMF_TRSTRING_MAX_LEN + 1];
4559 :
4560 : enum spdk_nvme_transport_type type;
4561 :
4562 : struct spdk_nvme_ctrlr *(*ctrlr_construct)(const struct spdk_nvme_transport_id *trid,
4563 : const struct spdk_nvme_ctrlr_opts *opts,
4564 : void *devhandle);
4565 :
4566 : int (*ctrlr_scan)(struct spdk_nvme_probe_ctx *probe_ctx, bool direct_connect);
4567 :
4568 : int (*ctrlr_destruct)(struct spdk_nvme_ctrlr *ctrlr);
4569 :
4570 : int (*ctrlr_enable)(struct spdk_nvme_ctrlr *ctrlr);
4571 :
4572 : int (*ctrlr_enable_interrupts)(struct spdk_nvme_ctrlr *ctrlr);
4573 :
4574 : int (*ctrlr_set_reg_4)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint32_t value);
4575 :
4576 : int (*ctrlr_set_reg_8)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint64_t value);
4577 :
4578 : int (*ctrlr_get_reg_4)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint32_t *value);
4579 :
4580 : int (*ctrlr_get_reg_8)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint64_t *value);
4581 :
4582 : int (*ctrlr_set_reg_4_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint32_t value,
4583 : spdk_nvme_reg_cb cb_fn, void *cb_arg);
4584 :
4585 : int (*ctrlr_set_reg_8_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset, uint64_t value,
4586 : spdk_nvme_reg_cb cb_fn, void *cb_arg);
4587 :
4588 : int (*ctrlr_get_reg_4_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset,
4589 : spdk_nvme_reg_cb cb_fn, void *cb_arg);
4590 :
4591 : int (*ctrlr_get_reg_8_async)(struct spdk_nvme_ctrlr *ctrlr, uint32_t offset,
4592 : spdk_nvme_reg_cb cb_fn, void *cb_arg);
4593 :
4594 : uint32_t (*ctrlr_get_max_xfer_size)(struct spdk_nvme_ctrlr *ctrlr);
4595 :
4596 : uint16_t (*ctrlr_get_max_sges)(struct spdk_nvme_ctrlr *ctrlr);
4597 :
4598 : int (*ctrlr_reserve_cmb)(struct spdk_nvme_ctrlr *ctrlr);
4599 :
4600 : void *(*ctrlr_map_cmb)(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
4601 :
4602 : int (*ctrlr_unmap_cmb)(struct spdk_nvme_ctrlr *ctrlr);
4603 :
4604 : int (*ctrlr_enable_pmr)(struct spdk_nvme_ctrlr *ctrlr);
4605 :
4606 : int (*ctrlr_disable_pmr)(struct spdk_nvme_ctrlr *ctrlr);
4607 :
4608 : void *(*ctrlr_map_pmr)(struct spdk_nvme_ctrlr *ctrlr, size_t *size);
4609 :
4610 : int (*ctrlr_unmap_pmr)(struct spdk_nvme_ctrlr *ctrlr);
4611 :
4612 : struct spdk_nvme_qpair *(*ctrlr_create_io_qpair)(struct spdk_nvme_ctrlr *ctrlr, uint16_t qid,
4613 : const struct spdk_nvme_io_qpair_opts *opts);
4614 :
4615 : int (*ctrlr_delete_io_qpair)(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
4616 :
4617 : int (*ctrlr_connect_qpair)(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
4618 :
4619 : void (*ctrlr_disconnect_qpair)(struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair);
4620 :
4621 : void (*qpair_abort_reqs)(struct spdk_nvme_qpair *qpair, uint32_t dnr);
4622 :
4623 : int (*qpair_reset)(struct spdk_nvme_qpair *qpair);
4624 :
4625 : int (*qpair_submit_request)(struct spdk_nvme_qpair *qpair, struct nvme_request *req);
4626 :
4627 : int (*qpair_authenticate)(struct spdk_nvme_qpair *qpair);
4628 :
4629 : int32_t (*qpair_process_completions)(struct spdk_nvme_qpair *qpair, uint32_t max_completions);
4630 :
4631 : int (*qpair_iterate_requests)(struct spdk_nvme_qpair *qpair,
4632 : int (*iter_fn)(struct nvme_request *req, void *arg),
4633 : void *arg);
4634 :
4635 : int (*qpair_get_fd)(struct spdk_nvme_qpair *qpair, struct spdk_event_handler_opts *opts);
4636 :
4637 : void (*admin_qpair_abort_aers)(struct spdk_nvme_qpair *qpair);
4638 :
4639 : struct spdk_nvme_transport_poll_group *(*poll_group_create)(void);
4640 : struct spdk_nvme_transport_poll_group *(*qpair_get_optimal_poll_group)(
4641 : struct spdk_nvme_qpair *qpair);
4642 :
4643 : int (*poll_group_add)(struct spdk_nvme_transport_poll_group *tgroup, struct spdk_nvme_qpair *qpair);
4644 :
4645 : int (*poll_group_remove)(struct spdk_nvme_transport_poll_group *tgroup,
4646 : struct spdk_nvme_qpair *qpair);
4647 :
4648 : int (*poll_group_connect_qpair)(struct spdk_nvme_qpair *qpair);
4649 :
4650 : int (*poll_group_disconnect_qpair)(struct spdk_nvme_qpair *qpair);
4651 :
4652 : int64_t (*poll_group_process_completions)(struct spdk_nvme_transport_poll_group *tgroup,
4653 : uint32_t completions_per_qpair, spdk_nvme_disconnected_qpair_cb disconnected_qpair_cb);
4654 :
4655 : void (*poll_group_check_disconnected_qpairs)(struct spdk_nvme_transport_poll_group *tgroup,
4656 : spdk_nvme_disconnected_qpair_cb disconnected_qpair_cb);
4657 :
4658 : int (*poll_group_destroy)(struct spdk_nvme_transport_poll_group *tgroup);
4659 :
4660 : int (*poll_group_get_stats)(struct spdk_nvme_transport_poll_group *tgroup,
4661 : struct spdk_nvme_transport_poll_group_stat **stats);
4662 :
4663 : void (*poll_group_free_stats)(struct spdk_nvme_transport_poll_group *tgroup,
4664 : struct spdk_nvme_transport_poll_group_stat *stats);
4665 :
4666 : int (*ctrlr_get_memory_domains)(const struct spdk_nvme_ctrlr *ctrlr,
4667 : struct spdk_memory_domain **domains,
4668 : int array_size);
4669 :
4670 : int (*ctrlr_ready)(struct spdk_nvme_ctrlr *ctrlr);
4671 :
4672 : volatile struct spdk_nvme_registers *(*ctrlr_get_registers)(struct spdk_nvme_ctrlr *ctrlr);
4673 :
4674 : /* Optional callback for transports to process removal events of attached controllers. */
4675 : int (*ctrlr_scan_attached)(struct spdk_nvme_probe_ctx *probe_ctx);
4676 : };
4677 :
4678 : /**
4679 : * Register the operations for a given transport type.
4680 : *
4681 : * This function should be invoked by referencing the macro
4682 : * SPDK_NVME_TRANSPORT_REGISTER macro in the transport's .c file.
4683 : *
4684 : * \param ops The operations associated with an NVMe-oF transport.
4685 : */
4686 : void spdk_nvme_transport_register(const struct spdk_nvme_transport_ops *ops);
4687 :
4688 : /*
4689 : * Macro used to register new transports.
4690 : */
4691 : #define SPDK_NVME_TRANSPORT_REGISTER(name, transport_ops) \
4692 : static void __attribute__((constructor)) _spdk_nvme_transport_register_##name(void) \
4693 : { \
4694 : spdk_nvme_transport_register(transport_ops); \
4695 : }
4696 :
4697 : /**
4698 : * NVMe transport options.
4699 : */
4700 : struct spdk_nvme_transport_opts {
4701 : /**
4702 : * It is used for RDMA transport.
4703 : *
4704 : * The queue depth of a shared rdma receive queue.
4705 : */
4706 : uint32_t rdma_srq_size;
4707 :
4708 : /* Hole at bytes 4-7. */
4709 : uint8_t reserved4[4];
4710 :
4711 : /**
4712 : * The size of spdk_nvme_transport_opts according to the caller of this library is used for ABI
4713 : * compatibility. The library uses this field to know how many fields in this
4714 : * structure are valid. And the library will populate any remaining fields with default values.
4715 : */
4716 : size_t opts_size;
4717 :
4718 : /**
4719 : * It is used for RDMA transport.
4720 : *
4721 : * The maximum queue depth of a rdma completion queue.
4722 : * It is zero, which means unlimited, by default.
4723 : */
4724 : uint32_t rdma_max_cq_size;
4725 :
4726 : /**
4727 : * It is used for RDMA transport.
4728 : *
4729 : * RDMA CM event timeout in milliseconds.
4730 : */
4731 : uint16_t rdma_cm_event_timeout_ms;
4732 : };
4733 : SPDK_STATIC_ASSERT(sizeof(struct spdk_nvme_transport_opts) == 24, "Incorrect size");
4734 :
4735 : /**
4736 : * Get the current NVMe transport options.
4737 : *
4738 : * \param[out] opts Will be filled with the current options for spdk_nvme_transport_set_opts().
4739 : * \param opts_size Must be set to sizeof(struct spdk_nvme_transport_opts).
4740 : */
4741 : void spdk_nvme_transport_get_opts(struct spdk_nvme_transport_opts *opts, size_t opts_size);
4742 :
4743 : /**
4744 : * Set the NVMe transport options.
4745 : *
4746 : * \param opts Pointer to the allocated spdk_nvme_transport_opts structure with new values.
4747 : * \param opts_size Must be set to sizeof(struct spdk_nvme_transport_opts).
4748 : *
4749 : * \return 0 on success, or negated errno on failure.
4750 : */
4751 : int spdk_nvme_transport_set_opts(const struct spdk_nvme_transport_opts *opts, size_t opts_size);
4752 :
4753 : #ifdef __cplusplus
4754 : }
4755 : #endif
4756 :
4757 : #endif
|
