]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
4 | * Copyright (c) Intel Corporation. | |
5 | * All rights reserved. | |
6 | * | |
7 | * Redistribution and use in source and binary forms, with or without | |
8 | * modification, are permitted provided that the following conditions | |
9 | * are met: | |
10 | * | |
11 | * * Redistributions of source code must retain the above copyright | |
12 | * notice, this list of conditions and the following disclaimer. | |
13 | * * Redistributions in binary form must reproduce the above copyright | |
14 | * notice, this list of conditions and the following disclaimer in | |
15 | * the documentation and/or other materials provided with the | |
16 | * distribution. | |
17 | * * Neither the name of Intel Corporation nor the names of its | |
18 | * contributors may be used to endorse or promote products derived | |
19 | * from this software without specific prior written permission. | |
20 | * | |
21 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
22 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
23 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
24 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
25 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
26 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
27 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
28 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
29 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
30 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
31 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
32 | */ | |
33 | ||
34 | /** \file | |
35 | * NVMe driver public API | |
36 | */ | |
37 | ||
38 | #ifndef SPDK_NVME_H | |
39 | #define SPDK_NVME_H | |
40 | ||
11fdf7f2 TL |
41 | #include "spdk/stdinc.h" |
42 | ||
7c673cae FG |
43 | #ifdef __cplusplus |
44 | extern "C" { | |
45 | #endif | |
46 | ||
7c673cae FG |
47 | #include "spdk/env.h" |
48 | #include "spdk/nvme_spec.h" | |
49 | #include "spdk/nvmf_spec.h" | |
50 | ||
51 | #define SPDK_NVME_DEFAULT_RETRY_COUNT (4) | |
52 | extern int32_t spdk_nvme_retry_count; | |
53 | ||
54 | ||
55 | ||
11fdf7f2 TL |
56 | /** |
57 | * Opaque handle to a controller. Returned by spdk_nvme_probe()'s attach_cb. | |
58 | */ | |
7c673cae FG |
59 | struct spdk_nvme_ctrlr; |
60 | ||
61 | /** | |
11fdf7f2 | 62 | * NVMe controller initialization options. |
7c673cae FG |
63 | * |
64 | * A pointer to this structure will be provided for each probe callback from spdk_nvme_probe() to | |
65 | * allow the user to request non-default options, and the actual options enabled on the controller | |
66 | * will be provided during the attach callback. | |
67 | */ | |
68 | struct spdk_nvme_ctrlr_opts { | |
69 | /** | |
70 | * Number of I/O queues to request (used to set Number of Queues feature) | |
71 | */ | |
72 | uint32_t num_io_queues; | |
73 | ||
74 | /** | |
75 | * Enable submission queue in controller memory buffer | |
76 | */ | |
77 | bool use_cmb_sqs; | |
78 | ||
79 | /** | |
80 | * Type of arbitration mechanism | |
81 | */ | |
82 | enum spdk_nvme_cc_ams arb_mechanism; | |
83 | ||
84 | /** | |
85 | * Keep alive timeout in milliseconds (0 = disabled). | |
86 | * | |
87 | * The NVMe library will set the Keep Alive Timer feature to this value and automatically | |
88 | * send Keep Alive commands as needed. The library user must call | |
89 | * spdk_nvme_ctrlr_process_admin_completions() periodically to ensure Keep Alive commands | |
90 | * are sent. | |
91 | */ | |
92 | uint32_t keep_alive_timeout_ms; | |
93 | ||
94 | /** | |
95 | * Specify the retry number when there is issue with the transport | |
96 | */ | |
97 | int transport_retry_count; | |
98 | ||
99 | /** | |
100 | * The queue depth of each NVMe I/O queue. | |
101 | */ | |
102 | uint32_t io_queue_size; | |
103 | ||
104 | /** | |
105 | * The host NQN to use when connecting to NVMe over Fabrics controllers. | |
106 | * | |
107 | * Unused for local PCIe-attached NVMe devices. | |
108 | */ | |
109 | char hostnqn[SPDK_NVMF_NQN_MAX_LEN + 1]; | |
110 | ||
111 | /** | |
112 | * The number of requests to allocate for each NVMe I/O queue. | |
113 | * | |
114 | * This should be at least as large as io_queue_size. | |
115 | * | |
116 | * A single I/O may allocate more than one request, since splitting may be necessary to | |
117 | * conform to the device's maximum transfer size, PRP list compatibility requirements, | |
118 | * or driver-assisted striping. | |
119 | */ | |
120 | uint32_t io_queue_requests; | |
11fdf7f2 TL |
121 | |
122 | /** | |
123 | * Source address for NVMe-oF connections. | |
124 | * Set src_addr and src_svcid to empty strings if no source address should be | |
125 | * specified. | |
126 | */ | |
127 | char src_addr[SPDK_NVMF_TRADDR_MAX_LEN + 1]; | |
128 | ||
129 | /** | |
130 | * Source service ID (port) for NVMe-oF connections. | |
131 | * Set src_addr and src_svcid to empty strings if no source address should be | |
132 | * specified. | |
133 | */ | |
134 | char src_svcid[SPDK_NVMF_TRSVCID_MAX_LEN + 1]; | |
135 | ||
136 | /** | |
137 | * The host identifier to use when connecting to controllers with 64-bit host ID support. | |
138 | * | |
139 | * Set to all zeroes to specify that no host ID should be provided to the controller. | |
140 | */ | |
141 | uint8_t host_id[8]; | |
142 | ||
143 | /** | |
144 | * The host identifier to use when connecting to controllers with extended (128-bit) host ID support. | |
145 | * | |
146 | * Set to all zeroes to specify that no host ID should be provided to the controller. | |
147 | */ | |
148 | uint8_t extended_host_id[16]; | |
149 | ||
150 | /** | |
151 | * The I/O command set to select. | |
152 | * | |
153 | * If the requested command set is not supported, the controller | |
154 | * initialization process will not proceed. By default, the NVM | |
155 | * command set is used. | |
156 | */ | |
157 | enum spdk_nvme_cc_css command_set; | |
7c673cae FG |
158 | }; |
159 | ||
11fdf7f2 TL |
160 | /** |
161 | * Get the default options for the creation of a specific NVMe controller. | |
162 | * | |
163 | * \param[out] opts Will be filled with the default option. | |
164 | * \param opts_size Must be set to sizeof(struct spdk_nvme_ctrlr_opts). | |
165 | */ | |
166 | void spdk_nvme_ctrlr_get_default_ctrlr_opts(struct spdk_nvme_ctrlr_opts *opts, | |
167 | size_t opts_size); | |
168 | ||
7c673cae FG |
169 | /** |
170 | * NVMe library transports | |
171 | * | |
172 | * NOTE: These are mapped directly to the NVMe over Fabrics TRTYPE values, except for PCIe, | |
173 | * which is a special case since NVMe over Fabrics does not define a TRTYPE for local PCIe. | |
174 | * | |
175 | * Currently, this uses 256 for PCIe which is intentionally outside of the 8-bit range of TRTYPE. | |
176 | * If the NVMe-oF specification ever defines a PCIe TRTYPE, this should be updated. | |
177 | */ | |
178 | enum spdk_nvme_transport_type { | |
179 | /** | |
180 | * PCIe Transport (locally attached devices) | |
181 | */ | |
182 | SPDK_NVME_TRANSPORT_PCIE = 256, | |
183 | ||
184 | /** | |
185 | * RDMA Transport (RoCE, iWARP, etc.) | |
186 | */ | |
187 | SPDK_NVME_TRANSPORT_RDMA = SPDK_NVMF_TRTYPE_RDMA, | |
11fdf7f2 TL |
188 | |
189 | /** | |
190 | * Fibre Channel (FC) Transport | |
191 | */ | |
192 | SPDK_NVME_TRANSPORT_FC = SPDK_NVMF_TRTYPE_FC, | |
7c673cae FG |
193 | }; |
194 | ||
195 | /** | |
196 | * NVMe transport identifier. | |
197 | * | |
198 | * This identifies a unique endpoint on an NVMe fabric. | |
199 | * | |
200 | * A string representation of a transport ID may be converted to this type using | |
201 | * spdk_nvme_transport_id_parse(). | |
202 | */ | |
203 | struct spdk_nvme_transport_id { | |
204 | /** | |
205 | * NVMe transport type. | |
206 | */ | |
207 | enum spdk_nvme_transport_type trtype; | |
208 | ||
209 | /** | |
210 | * Address family of the transport address. | |
211 | * | |
212 | * For PCIe, this value is ignored. | |
213 | */ | |
214 | enum spdk_nvmf_adrfam adrfam; | |
215 | ||
216 | /** | |
217 | * Transport address of the NVMe-oF endpoint. For transports which use IP | |
218 | * addressing (e.g. RDMA), this should be an IP address. For PCIe, this | |
219 | * can either be a zero length string (the whole bus) or a PCI address | |
11fdf7f2 TL |
220 | * in the format DDDD:BB:DD.FF or DDDD.BB.DD.FF. For FC the string is |
221 | * formatted as: nn-0xWWNN:pn-0xWWPN” where WWNN is the Node_Name of the | |
222 | * target NVMe_Port and WWPN is the N_Port_Name of the target NVMe_Port. | |
7c673cae FG |
223 | */ |
224 | char traddr[SPDK_NVMF_TRADDR_MAX_LEN + 1]; | |
225 | ||
226 | /** | |
227 | * Transport service id of the NVMe-oF endpoint. For transports which use | |
228 | * IP addressing (e.g. RDMA), this field shoud be the port number. For PCIe, | |
11fdf7f2 | 229 | * and FC this is always a zero length string. |
7c673cae FG |
230 | */ |
231 | char trsvcid[SPDK_NVMF_TRSVCID_MAX_LEN + 1]; | |
232 | ||
233 | /** | |
234 | * Subsystem NQN of the NVMe over Fabrics endpoint. May be a zero length string. | |
235 | */ | |
236 | char subnqn[SPDK_NVMF_NQN_MAX_LEN + 1]; | |
237 | }; | |
238 | ||
239 | /** | |
240 | * Parse the string representation of a transport ID. | |
241 | * | |
242 | * \param trid Output transport ID structure (must be allocated and initialized by caller). | |
243 | * \param str Input string representation of a transport ID to parse. | |
7c673cae | 244 | * |
11fdf7f2 TL |
245 | * str must be a zero-terminated C string containing one or more key:value pairs |
246 | * separated by whitespace. | |
7c673cae FG |
247 | * |
248 | * Key | Value | |
249 | * ------------ | ----- | |
250 | * trtype | Transport type (e.g. PCIe, RDMA) | |
251 | * adrfam | Address family (e.g. IPv4, IPv6) | |
11fdf7f2 | 252 | * traddr | Transport address (e.g. 0000:04:00.0 for PCIe, 192.168.100.8 for RDMA, or WWN for FC) |
7c673cae FG |
253 | * trsvcid | Transport service identifier (e.g. 4420) |
254 | * subnqn | Subsystem NQN | |
255 | * | |
11fdf7f2 TL |
256 | * Unspecified fields of trid are left unmodified, so the caller must initialize |
257 | * trid (for example, memset() to 0) before calling this function. | |
258 | * | |
259 | * \return 0 if parsing was successful and trid is filled out, or negated errno | |
260 | * values on failure. | |
7c673cae FG |
261 | */ |
262 | int spdk_nvme_transport_id_parse(struct spdk_nvme_transport_id *trid, const char *str); | |
263 | ||
264 | /** | |
265 | * Parse the string representation of a transport ID tranport type. | |
266 | * | |
267 | * \param trtype Output transport type (allocated by caller). | |
11fdf7f2 TL |
268 | * \param str Input string representation of transport type (e.g. "PCIe", "RDMA"). |
269 | * | |
270 | * \return 0 if parsing was successful and trtype is filled out, or negated errno | |
271 | * values on failure. | |
7c673cae FG |
272 | */ |
273 | int spdk_nvme_transport_id_parse_trtype(enum spdk_nvme_transport_type *trtype, const char *str); | |
274 | ||
11fdf7f2 TL |
275 | /** |
276 | * Look up the string representation of a transport ID transport type. | |
277 | * | |
278 | * \param trtype Transport type to convert. | |
279 | * | |
280 | * \return static string constant describing trtype, or NULL if trtype not found. | |
281 | */ | |
282 | const char *spdk_nvme_transport_id_trtype_str(enum spdk_nvme_transport_type trtype); | |
283 | ||
284 | /** | |
285 | * Look up the string representation of a transport ID address family. | |
286 | * | |
287 | * \param adrfam Address family to convert. | |
288 | * | |
289 | * \return static string constant describing adrfam, or NULL if adrmfam not found. | |
290 | */ | |
291 | const char *spdk_nvme_transport_id_adrfam_str(enum spdk_nvmf_adrfam adrfam); | |
292 | ||
7c673cae FG |
293 | /** |
294 | * Parse the string representation of a tranport ID address family. | |
295 | * | |
296 | * \param adrfam Output address family (allocated by caller). | |
11fdf7f2 TL |
297 | * \param str Input string representation of address family (e.g. "IPv4", "IPv6"). |
298 | * | |
299 | * \return 0 if parsing was successful and adrfam is filled out, or negated errno | |
300 | * values on failure. | |
7c673cae FG |
301 | */ |
302 | int spdk_nvme_transport_id_parse_adrfam(enum spdk_nvmf_adrfam *adrfam, const char *str); | |
303 | ||
304 | /** | |
305 | * Compare two transport IDs. | |
306 | * | |
11fdf7f2 TL |
307 | * The result of this function may be used to sort transport IDs in a consistent |
308 | * order; however, the comparison result is not guaranteed to be consistent across | |
309 | * library versions. | |
7c673cae | 310 | * |
11fdf7f2 TL |
311 | * This function uses a case-insensitive comparison for string fields, but it does |
312 | * not otherwise normalize the transport ID. It is the caller's responsibility to | |
313 | * provide the transport IDs in a consistent format. | |
7c673cae | 314 | * |
11fdf7f2 TL |
315 | * \param trid1 First transport ID to compare. |
316 | * \param trid2 Second transport ID to compare. | |
7c673cae | 317 | * |
11fdf7f2 TL |
318 | * \return 0 if trid1 == trid2, less than 0 if trid1 < trid2, greater than 0 if |
319 | * trid1 > trid2. | |
7c673cae FG |
320 | */ |
321 | int spdk_nvme_transport_id_compare(const struct spdk_nvme_transport_id *trid1, | |
322 | const struct spdk_nvme_transport_id *trid2); | |
323 | ||
324 | /** | |
11fdf7f2 TL |
325 | * Determine whether the NVMe library can handle a specific NVMe over Fabrics |
326 | * transport type. | |
7c673cae FG |
327 | * |
328 | * \param trtype NVMe over Fabrics transport type to check. | |
329 | * | |
330 | * \return true if trtype is supported or false if it is not supported. | |
331 | */ | |
332 | bool spdk_nvme_transport_available(enum spdk_nvme_transport_type trtype); | |
333 | ||
334 | /** | |
335 | * Callback for spdk_nvme_probe() enumeration. | |
336 | * | |
11fdf7f2 TL |
337 | * \param cb_ctx Opaque value passed to spdk_nvme_probe(). |
338 | * \param trid NVMe transport identifier. | |
339 | * \param opts NVMe controller initialization options. This structure will be | |
340 | * populated with the default values on entry, and the user callback may update | |
341 | * any options to request a different value. The controller may not support all | |
342 | * requested parameters, so the final values will be provided during the attach | |
343 | * callback. | |
344 | * | |
7c673cae FG |
345 | * \return true to attach to this device. |
346 | */ | |
347 | typedef bool (*spdk_nvme_probe_cb)(void *cb_ctx, const struct spdk_nvme_transport_id *trid, | |
348 | struct spdk_nvme_ctrlr_opts *opts); | |
349 | ||
350 | /** | |
11fdf7f2 TL |
351 | * Callback for spdk_nvme_attach() to report a device that has been attached to |
352 | * the userspace NVMe driver. | |
7c673cae | 353 | * |
11fdf7f2 TL |
354 | * \param cb_ctx Opaque value passed to spdk_nvme_attach_cb(). |
355 | * \param trid NVMe transport identifier. | |
356 | * \param ctrlr Opaque handle to NVMe controller. | |
357 | * \param opts NVMe controller initialization options that were actually used. | |
358 | * Options may differ from the requested options from the attach call depending | |
359 | * on what the controller supports. | |
7c673cae FG |
360 | */ |
361 | typedef void (*spdk_nvme_attach_cb)(void *cb_ctx, const struct spdk_nvme_transport_id *trid, | |
362 | struct spdk_nvme_ctrlr *ctrlr, | |
363 | const struct spdk_nvme_ctrlr_opts *opts); | |
364 | ||
365 | /** | |
11fdf7f2 TL |
366 | * Callback for spdk_nvme_remove() to report that a device attached to the userspace |
367 | * NVMe driver has been removed from the system. | |
7c673cae FG |
368 | * |
369 | * The controller will remain in a failed state (any new I/O submitted will fail). | |
370 | * | |
371 | * The controller must be detached from the userspace driver by calling spdk_nvme_detach() | |
11fdf7f2 TL |
372 | * once the controller is no longer in use. It is up to the library user to ensure |
373 | * that no other threads are using the controller before calling spdk_nvme_detach(). | |
7c673cae | 374 | * |
11fdf7f2 | 375 | * \param cb_ctx Opaque value passed to spdk_nvme_remove_cb(). |
7c673cae FG |
376 | * \param ctrlr NVMe controller instance that was removed. |
377 | */ | |
378 | typedef void (*spdk_nvme_remove_cb)(void *cb_ctx, struct spdk_nvme_ctrlr *ctrlr); | |
379 | ||
380 | /** | |
11fdf7f2 TL |
381 | * Enumerate the bus indicated by the transport ID and attach the userspace NVMe |
382 | * driver to each device found if desired. | |
7c673cae | 383 | * |
11fdf7f2 TL |
384 | * This function is not thread safe and should only be called from one thread at |
385 | * a time while no other threads are actively using any NVMe devices. | |
7c673cae | 386 | * |
11fdf7f2 TL |
387 | * If called from a secondary process, only devices that have been attached to |
388 | * the userspace driver in the primary process will be probed. | |
7c673cae | 389 | * |
11fdf7f2 TL |
390 | * If called more than once, only devices that are not already attached to the |
391 | * SPDK NVMe driver will be reported. | |
7c673cae FG |
392 | * |
393 | * To stop using the the controller and release its associated resources, | |
11fdf7f2 TL |
394 | * call spdk_nvme_detach() with the spdk_nvme_ctrlr instance from the attach_cb() |
395 | * function. | |
396 | * | |
397 | * \param trid The transport ID indicating which bus to enumerate. If the trtype | |
398 | * is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is | |
399 | * RDMA, the traddr and trsvcid must point at the location of an NVMe-oF discovery | |
400 | * service. | |
401 | * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of | |
402 | * the callbacks. | |
403 | * \param probe_cb will be called once per NVMe device found in the system. | |
404 | * \param attach_cb will be called for devices for which probe_cb returned true | |
405 | * once that NVMe controller has been attached to the userspace driver. | |
406 | * \param remove_cb will be called for devices that were attached in a previous | |
407 | * spdk_nvme_probe() call but are no longer attached to the system. Optional; | |
408 | * specify NULL if removal notices are not desired. | |
409 | * | |
410 | * \return 0 on success, -1 on failure. | |
7c673cae FG |
411 | */ |
412 | int spdk_nvme_probe(const struct spdk_nvme_transport_id *trid, | |
413 | void *cb_ctx, | |
414 | spdk_nvme_probe_cb probe_cb, | |
415 | spdk_nvme_attach_cb attach_cb, | |
416 | spdk_nvme_remove_cb remove_cb); | |
417 | ||
418 | /** | |
11fdf7f2 TL |
419 | * Connect the NVMe driver to the device located at the given transport ID. |
420 | * | |
421 | * This function is not thread safe and should only be called from one thread at | |
422 | * a time while no other threads are actively using this NVMe device. | |
423 | * | |
424 | * If called from a secondary process, only the device that has been attached to | |
425 | * the userspace driver in the primary process will be connected. | |
426 | * | |
427 | * If connecting to multiple controllers, it is suggested to use spdk_nvme_probe() | |
428 | * and filter the requested controllers with the probe callback. For PCIe controllers, | |
429 | * spdk_nvme_probe() will be more efficient since the controller resets will happen | |
430 | * in parallel. | |
431 | * | |
432 | * To stop using the the controller and release its associated resources, call | |
433 | * spdk_nvme_detach() with the spdk_nvme_ctrlr instance returned by this function. | |
434 | * | |
435 | * \param trid The transport ID indicating which device to connect. If the trtype | |
436 | * is PCIe, this will connect the local PCIe bus. If the trtype is RDMA, the traddr | |
437 | * and trsvcid must point at the location of an NVMe-oF service. | |
438 | * \param opts NVMe controller initialization options. Default values will be used | |
439 | * if the user does not specify the options. The controller may not support all | |
440 | * requested parameters. | |
441 | * \param opts_size Must be set to sizeof(struct spdk_nvme_ctrlr_opts), or 0 if | |
442 | * opts is NULL. | |
443 | * | |
444 | * \return pointer to the connected NVMe controller or NULL if there is any failure. | |
445 | * | |
446 | */ | |
447 | struct spdk_nvme_ctrlr *spdk_nvme_connect(const struct spdk_nvme_transport_id *trid, | |
448 | const struct spdk_nvme_ctrlr_opts *opts, | |
449 | size_t opts_size); | |
450 | ||
451 | /** | |
452 | * Detach specified device returned by spdk_nvme_probe()'s attach_cb from the | |
453 | * NVMe driver. | |
7c673cae FG |
454 | * |
455 | * On success, the spdk_nvme_ctrlr handle is no longer valid. | |
456 | * | |
457 | * This function should be called from a single thread while no other threads | |
458 | * are actively using the NVMe device. | |
459 | * | |
11fdf7f2 TL |
460 | * \param ctrlr Opaque handle to NVMe controller. |
461 | * | |
462 | * \return 0 on success, -1 on failure. | |
7c673cae FG |
463 | */ |
464 | int spdk_nvme_detach(struct spdk_nvme_ctrlr *ctrlr); | |
465 | ||
466 | /** | |
11fdf7f2 | 467 | * Perform a full hardware reset of the NVMe controller. |
7c673cae FG |
468 | * |
469 | * This function should be called from a single thread while no other threads | |
470 | * are actively using the NVMe device. | |
471 | * | |
11fdf7f2 TL |
472 | * Any pointers returned from spdk_nvme_ctrlr_get_ns() and spdk_nvme_ns_get_data() |
473 | * may be invalidated by calling this function. The number of namespaces as returned | |
474 | * by spdk_nvme_ctrlr_get_num_ns() may also change. | |
475 | * | |
476 | * \param ctrlr Opaque handle to NVMe controller. | |
477 | * | |
478 | * \return 0 on success, -1 on failure. | |
7c673cae FG |
479 | */ |
480 | int spdk_nvme_ctrlr_reset(struct spdk_nvme_ctrlr *ctrlr); | |
481 | ||
482 | /** | |
11fdf7f2 | 483 | * Get the identify controller data as defined by the NVMe specification. |
7c673cae | 484 | * |
11fdf7f2 TL |
485 | * This function is thread safe and can be called at any point while the controller |
486 | * is attached to the SPDK NVMe driver. | |
7c673cae | 487 | * |
11fdf7f2 TL |
488 | * \param ctrlr Opaque handle to NVMe controller. |
489 | * | |
490 | * \return pointer to the identify controller data. | |
7c673cae FG |
491 | */ |
492 | const struct spdk_nvme_ctrlr_data *spdk_nvme_ctrlr_get_data(struct spdk_nvme_ctrlr *ctrlr); | |
493 | ||
494 | /** | |
11fdf7f2 TL |
495 | * Get the NVMe controller CSTS (Status) register. |
496 | * | |
497 | * \param ctrlr Opaque handle to NVMe controller. | |
498 | * | |
499 | * \return the NVMe controller CSTS (Status) register. | |
7c673cae FG |
500 | */ |
501 | union spdk_nvme_csts_register spdk_nvme_ctrlr_get_regs_csts(struct spdk_nvme_ctrlr *ctrlr); | |
502 | ||
503 | /** | |
11fdf7f2 TL |
504 | * Get the NVMe controller CAP (Capabilities) register. |
505 | * | |
506 | * \param ctrlr Opaque handle to NVMe controller. | |
507 | * | |
508 | * \return the NVMe controller CAP (Capabilities) register. | |
7c673cae FG |
509 | */ |
510 | union spdk_nvme_cap_register spdk_nvme_ctrlr_get_regs_cap(struct spdk_nvme_ctrlr *ctrlr); | |
511 | ||
512 | /** | |
11fdf7f2 TL |
513 | * Get the NVMe controller VS (Version) register. |
514 | * | |
515 | * \param ctrlr Opaque handle to NVMe controller. | |
516 | * | |
517 | * \return the NVMe controller VS (Version) register. | |
7c673cae FG |
518 | */ |
519 | union spdk_nvme_vs_register spdk_nvme_ctrlr_get_regs_vs(struct spdk_nvme_ctrlr *ctrlr); | |
520 | ||
521 | /** | |
11fdf7f2 | 522 | * Get the number of namespaces for the given NVMe controller. |
7c673cae | 523 | * |
11fdf7f2 TL |
524 | * This function is thread safe and can be called at any point while the |
525 | * controller is attached to the SPDK NVMe driver. | |
7c673cae FG |
526 | * |
527 | * This is equivalent to calling spdk_nvme_ctrlr_get_data() to get the | |
528 | * spdk_nvme_ctrlr_data and then reading the nn field. | |
529 | * | |
11fdf7f2 TL |
530 | * \param ctrlr Opaque handle to NVMe controller. |
531 | * | |
532 | * \return the number of namespaces. | |
7c673cae FG |
533 | */ |
534 | uint32_t spdk_nvme_ctrlr_get_num_ns(struct spdk_nvme_ctrlr *ctrlr); | |
535 | ||
536 | /** | |
11fdf7f2 TL |
537 | * Get the PCI device of a given NVMe controller. |
538 | * | |
539 | * This only works for local (PCIe-attached) NVMe controllers; other transports | |
540 | * will return NULL. | |
541 | * | |
542 | * \param ctrlr Opaque handle to NVMe controller. | |
543 | * | |
544 | * \return PCI device of the NVMe controller, or NULL if not available. | |
545 | */ | |
546 | struct spdk_pci_device *spdk_nvme_ctrlr_get_pci_device(struct spdk_nvme_ctrlr *ctrlr); | |
547 | ||
548 | /** | |
549 | * Get the maximum data transfer size of a given NVMe controller. | |
550 | * | |
551 | * \return Maximum data transfer size of the NVMe controller in bytes. | |
552 | * | |
553 | * The I/O command helper functions, such as spdk_nvme_ns_cmd_read(), will split | |
554 | * large I/Os automatically; however, it is up to the user to obey this limit for | |
555 | * commands submitted with the raw command functions, such as spdk_nvme_ctrlr_cmd_io_raw(). | |
556 | */ | |
557 | uint32_t spdk_nvme_ctrlr_get_max_xfer_size(const struct spdk_nvme_ctrlr *ctrlr); | |
558 | ||
559 | /** | |
560 | * Check whether the nsid is an active nv for the given NVMe controller. | |
561 | * | |
562 | * This function is thread safe and can be called at any point while the controller | |
563 | * is attached to the SPDK NVMe driver. | |
564 | * | |
565 | * \param ctrlr Opaque handle to NVMe controller. | |
566 | * \param nsid Namespace id. | |
567 | * | |
568 | * \return true if nsid is an active ns, or false otherwise. | |
569 | */ | |
570 | bool spdk_nvme_ctrlr_is_active_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid); | |
571 | ||
572 | /** | |
573 | * Get the nsid of the first active namespace. | |
574 | * | |
575 | * This function is thread safe and can be called at any point while the controller | |
576 | * is attached to the SPDK NVMe driver. | |
577 | * | |
578 | * \param ctrlr Opaque handle to NVMe controller. | |
579 | * | |
580 | * \return the nsid of the first active namespace, 0 if there are no active namespaces. | |
581 | */ | |
582 | uint32_t spdk_nvme_ctrlr_get_first_active_ns(struct spdk_nvme_ctrlr *ctrlr); | |
583 | ||
584 | /** | |
585 | * Get next active namespace given the previous nsid. | |
586 | * | |
587 | * This function is thread safe and can be called at any point while the controller | |
588 | * is attached to the SPDK NVMe driver. | |
589 | * | |
590 | * \param ctrlr Opaque handle to NVMe controller. | |
591 | * \param prev_nsid Namespace id. | |
592 | * | |
593 | * \return a next active namespace given the previous nsid, 0 when there are no | |
594 | * more active namespaces. | |
595 | */ | |
596 | uint32_t spdk_nvme_ctrlr_get_next_active_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t prev_nsid); | |
597 | ||
598 | /** | |
599 | * Determine if a particular log page is supported by the given NVMe controller. | |
600 | * | |
601 | * This function is thread safe and can be called at any point while the controller | |
602 | * is attached to the SPDK NVMe driver. | |
7c673cae | 603 | * |
11fdf7f2 | 604 | * \sa spdk_nvme_ctrlr_cmd_get_log_page(). |
7c673cae | 605 | * |
11fdf7f2 TL |
606 | * \param ctrlr Opaque handle to NVMe controller. |
607 | * \param log_page Log page to query. | |
608 | * | |
609 | * \return true if supported, or false otherwise. | |
7c673cae FG |
610 | */ |
611 | bool spdk_nvme_ctrlr_is_log_page_supported(struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page); | |
612 | ||
613 | /** | |
11fdf7f2 TL |
614 | * Determine if a particular feature is supported by the given NVMe controller. |
615 | * | |
616 | * This function is thread safe and can be called at any point while the controller | |
617 | * is attached to the SPDK NVMe driver. | |
7c673cae | 618 | * |
11fdf7f2 | 619 | * \sa spdk_nvme_ctrlr_cmd_get_feature(). |
7c673cae | 620 | * |
11fdf7f2 TL |
621 | * \param ctrlr Opaque handle to NVMe controller. |
622 | * \param feature_code Feature to query. | |
623 | * | |
624 | * \return true if supported, or false otherwise. | |
7c673cae FG |
625 | */ |
626 | bool spdk_nvme_ctrlr_is_feature_supported(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature_code); | |
627 | ||
628 | /** | |
629 | * Signature for callback function invoked when a command is completed. | |
630 | * | |
11fdf7f2 | 631 | * \param spdk_nvme_cpl Completion queue entry that coontains the completion status. |
7c673cae FG |
632 | */ |
633 | typedef void (*spdk_nvme_cmd_cb)(void *, const struct spdk_nvme_cpl *); | |
634 | ||
635 | /** | |
11fdf7f2 TL |
636 | * Signature for callback function invoked when an asynchronous error request |
637 | * command is completed. | |
7c673cae | 638 | * |
11fdf7f2 TL |
639 | * \param ctrlr Opaque handle to NVMe controller. |
640 | * \param aer_cb_arg Context specified by spdk_nvme_register_aer_callback(). | |
641 | * \param spdk_nvme_cpl Completion queue entry that contains the completion status | |
642 | * of the asynchronous event request that was completed. | |
7c673cae FG |
643 | */ |
644 | typedef void (*spdk_nvme_aer_cb)(void *aer_cb_arg, | |
645 | const struct spdk_nvme_cpl *); | |
646 | ||
11fdf7f2 TL |
647 | /** |
648 | * Register callback function invoked when an AER command is completed for the | |
649 | * given NVMe controller. | |
650 | * | |
651 | * \param ctrlr Opaque handle to NVMe controller. | |
652 | * \param aer_cb_fn Callback function invoked when an asynchronous error request | |
653 | * command is completed. | |
654 | * \param aer_cb_arg Argument passed to callback function. | |
655 | */ | |
7c673cae FG |
656 | void spdk_nvme_ctrlr_register_aer_callback(struct spdk_nvme_ctrlr *ctrlr, |
657 | spdk_nvme_aer_cb aer_cb_fn, | |
658 | void *aer_cb_arg); | |
659 | ||
660 | /** | |
11fdf7f2 | 661 | * Opaque handle to a queue pair. |
7c673cae FG |
662 | * |
663 | * I/O queue pairs may be allocated using spdk_nvme_ctrlr_alloc_io_qpair(). | |
664 | */ | |
665 | struct spdk_nvme_qpair; | |
666 | ||
667 | /** | |
11fdf7f2 TL |
668 | * Signature for the callback function invoked when a timeout is detected on a |
669 | * request. | |
670 | * | |
671 | * For timeouts detected on the admin queue pair, the qpair returned here will | |
672 | * be NULL. If the controller has a serious error condition and is unable to | |
673 | * communicate with driver via completion queue, the controller can set Controller | |
674 | * Fatal Status field to 1, then reset is required to recover from such error. | |
675 | * Users may detect Controller Fatal Status when timeout happens. | |
676 | * | |
677 | * \param cb_arg Argument passed to callback funciton. | |
678 | * \param ctrlr Opaque handle to NVMe controller. | |
679 | * \param qpair Opaque handle to a queue pair. | |
680 | * \param cid Command ID. | |
7c673cae FG |
681 | */ |
682 | typedef void (*spdk_nvme_timeout_cb)(void *cb_arg, | |
683 | struct spdk_nvme_ctrlr *ctrlr, | |
684 | struct spdk_nvme_qpair *qpair, | |
685 | uint16_t cid); | |
686 | ||
687 | /** | |
11fdf7f2 | 688 | * Register for timeout callback on a controller. |
7c673cae FG |
689 | * |
690 | * The application can choose to register for timeout callback or not register | |
691 | * for timeout callback. | |
692 | * | |
693 | * \param ctrlr NVMe controller on which to monitor for timeout. | |
11fdf7f2 TL |
694 | * \param timeout_us Timeout value in microseconds. |
695 | * \param cb_fn A function pointer that points to the callback function. | |
7c673cae FG |
696 | * \param cb_arg Argument to the callback function. |
697 | */ | |
698 | void spdk_nvme_ctrlr_register_timeout_callback(struct spdk_nvme_ctrlr *ctrlr, | |
11fdf7f2 TL |
699 | uint64_t timeout_us, spdk_nvme_timeout_cb cb_fn, void *cb_arg); |
700 | ||
701 | /** | |
702 | * NVMe I/O queue pair initialization options. | |
703 | * | |
704 | * These options may be passed to spdk_nvme_ctrlr_alloc_io_qpair() to configure queue pair | |
705 | * options at queue creation time. | |
706 | * | |
707 | * The user may retrieve the default I/O queue pair creation options for a controller using | |
708 | * spdk_nvme_ctrlr_get_default_io_qpair_opts(). | |
709 | */ | |
710 | struct spdk_nvme_io_qpair_opts { | |
711 | /** | |
712 | * Queue priority for weighted round robin arbitration. If a different arbitration | |
713 | * method is in use, pass 0. | |
714 | */ | |
715 | enum spdk_nvme_qprio qprio; | |
716 | ||
717 | /** | |
718 | * The queue depth of this NVMe I/O queue. Overrides spdk_nvme_ctrlr_opts::io_queue_size. | |
719 | */ | |
720 | uint32_t io_queue_size; | |
721 | ||
722 | /** | |
723 | * The number of requests to allocate for this NVMe I/O queue. | |
724 | * | |
725 | * Overrides spdk_nvme_ctrlr_opts::io_queue_requests. | |
726 | * | |
727 | * This should be at least as large as io_queue_size. | |
728 | * | |
729 | * A single I/O may allocate more than one request, since splitting may be | |
730 | * necessary to conform to the device's maximum transfer size, PRP list | |
731 | * compatibility requirements, or driver-assisted striping. | |
732 | */ | |
733 | uint32_t io_queue_requests; | |
734 | }; | |
735 | ||
736 | /** | |
737 | * Get the default options for I/O qpair creation for a specific NVMe controller. | |
738 | * | |
739 | * \param ctrlr NVMe controller to retrieve the defaults from. | |
740 | * \param[out] opts Will be filled with the default options for | |
741 | * spdk_nvme_ctrlr_alloc_io_qpair(). | |
742 | * \param opts_size Must be set to sizeof(struct spdk_nvme_io_qpair_opts). | |
743 | */ | |
744 | void spdk_nvme_ctrlr_get_default_io_qpair_opts(struct spdk_nvme_ctrlr *ctrlr, | |
745 | struct spdk_nvme_io_qpair_opts *opts, | |
746 | size_t opts_size); | |
7c673cae FG |
747 | |
748 | /** | |
11fdf7f2 | 749 | * Allocate an I/O queue pair (submission and completion queue). |
7c673cae | 750 | * |
11fdf7f2 TL |
751 | * Each queue pair should only be used from a single thread at a time (mutual |
752 | * exclusion must be enforced by the user). | |
7c673cae FG |
753 | * |
754 | * \param ctrlr NVMe controller for which to allocate the I/O queue pair. | |
11fdf7f2 TL |
755 | * \param opts I/O qpair creation options, or NULL to use the defaults as returned |
756 | * by spdk_nvme_ctrlr_alloc_io_qpair(). | |
757 | * \param opts_size Must be set to sizeof(struct spdk_nvme_io_qpair_opts), or 0 | |
758 | * if opts is NULL. | |
759 | * | |
760 | * \return a pointer to the allocated I/O queue pair. | |
7c673cae FG |
761 | */ |
762 | struct spdk_nvme_qpair *spdk_nvme_ctrlr_alloc_io_qpair(struct spdk_nvme_ctrlr *ctrlr, | |
11fdf7f2 TL |
763 | const struct spdk_nvme_io_qpair_opts *opts, |
764 | size_t opts_size); | |
7c673cae FG |
765 | |
766 | /** | |
11fdf7f2 TL |
767 | * Free an I/O queue pair that was allocated by spdk_nvme_ctrlr_alloc_io_qpair(). |
768 | * | |
769 | * \param qpair I/O queue pair to free. | |
770 | * | |
771 | * \return 0 on success, -1 on failure. | |
7c673cae FG |
772 | */ |
773 | int spdk_nvme_ctrlr_free_io_qpair(struct spdk_nvme_qpair *qpair); | |
774 | ||
775 | /** | |
11fdf7f2 | 776 | * Send the given NVM I/O command to the NVMe controller. |
7c673cae FG |
777 | * |
778 | * This is a low level interface for submitting I/O commands directly. Prefer | |
779 | * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will | |
780 | * not be checked! | |
781 | * | |
782 | * When constructing the nvme_command it is not necessary to fill out the PRP | |
783 | * list/SGL or the CID. The driver will handle both of those for you. | |
784 | * | |
785 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
786 | * The user must ensure that only one thread submits I/O on a given qpair at any |
787 | * given time. | |
788 | * | |
789 | * \param ctrlr Opaque handle to NVMe controller. | |
790 | * \param qpair I/O qpair to submit command. | |
791 | * \param cmd NVM I/O command to submit. | |
792 | * \param buf Virtual memory address of a single physically contiguous buffer. | |
793 | * \param len Size of buffer. | |
794 | * \param cb_fn Callback function invoked when the I/O command completes. | |
795 | * \param cb_arg Argument passed to callback function. | |
796 | * | |
797 | * \return 0 on success, negated errno on failure. | |
7c673cae FG |
798 | */ |
799 | int spdk_nvme_ctrlr_cmd_io_raw(struct spdk_nvme_ctrlr *ctrlr, | |
800 | struct spdk_nvme_qpair *qpair, | |
801 | struct spdk_nvme_cmd *cmd, | |
802 | void *buf, uint32_t len, | |
803 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
804 | ||
805 | /** | |
11fdf7f2 TL |
806 | * Send the given NVM I/O command with metadata to the NVMe controller. |
807 | * | |
808 | * This is a low level interface for submitting I/O commands directly. Prefer | |
809 | * the spdk_nvme_ns_cmd_* functions instead. The validity of the command will | |
810 | * not be checked! | |
811 | * | |
812 | * When constructing the nvme_command it is not necessary to fill out the PRP | |
813 | * list/SGL or the CID. The driver will handle both of those for you. | |
814 | * | |
815 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
816 | * The user must ensure that only one thread submits I/O on a given qpair at any | |
817 | * given time. | |
818 | * | |
819 | * \param ctrlr Opaque handle to NVMe controller. | |
820 | * \param qpair I/O qpair to submit command. | |
821 | * \param cmd NVM I/O command to submit. | |
822 | * \param buf Virtual memory address of a single physically contiguous buffer. | |
823 | * \param len Size of buffer. | |
824 | * \param md_buf Virtual memory address of a single physically contiguous metadata | |
825 | * buffer. | |
826 | * \param cb_fn Callback function invoked when the I/O command completes. | |
827 | * \param cb_arg Argument passed to callback function. | |
828 | * | |
829 | * \return 0 on success, negated errno on failure. | |
830 | */ | |
831 | int spdk_nvme_ctrlr_cmd_io_raw_with_md(struct spdk_nvme_ctrlr *ctrlr, | |
832 | struct spdk_nvme_qpair *qpair, | |
833 | struct spdk_nvme_cmd *cmd, | |
834 | void *buf, uint32_t len, void *md_buf, | |
835 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
836 | ||
837 | /** | |
838 | * Process any outstanding completions for I/O submitted on a queue pair. | |
7c673cae | 839 | * |
11fdf7f2 TL |
840 | * This call is non-blocking, i.e. it only processes completions that are ready |
841 | * at the time of this function call. It does not wait for outstanding commands | |
842 | * to finish. | |
7c673cae | 843 | * |
11fdf7f2 TL |
844 | * For each completed command, the request's callback function will be called if |
845 | * specified as non-NULL when the request was submitted. | |
7c673cae | 846 | * |
11fdf7f2 TL |
847 | * The caller must ensure that each queue pair is only used from one thread at a |
848 | * time. | |
7c673cae | 849 | * |
11fdf7f2 TL |
850 | * This function may be called at any point while the controller is attached to |
851 | * the SPDK NVMe driver. | |
7c673cae FG |
852 | * |
853 | * \sa spdk_nvme_cmd_cb | |
854 | * | |
11fdf7f2 TL |
855 | * \param qpair Queue pair to check for completions. |
856 | * \param max_completions Limit the number of completions to be processed in one | |
857 | * call, or 0 for unlimited. | |
7c673cae | 858 | * |
11fdf7f2 | 859 | * \return number of completions processed (may be 0) or negated on error. |
7c673cae FG |
860 | */ |
861 | int32_t spdk_nvme_qpair_process_completions(struct spdk_nvme_qpair *qpair, | |
862 | uint32_t max_completions); | |
863 | ||
864 | /** | |
11fdf7f2 | 865 | * Send the given admin command to the NVMe controller. |
7c673cae FG |
866 | * |
867 | * This is a low level interface for submitting admin commands directly. Prefer | |
868 | * the spdk_nvme_ctrlr_cmd_* functions instead. The validity of the command will | |
869 | * not be checked! | |
870 | * | |
871 | * When constructing the nvme_command it is not necessary to fill out the PRP | |
872 | * list/SGL or the CID. The driver will handle both of those for you. | |
873 | * | |
11fdf7f2 TL |
874 | * This function is thread safe and can be called at any point while the controller |
875 | * is attached to the SPDK NVMe driver. | |
7c673cae | 876 | * |
11fdf7f2 | 877 | * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion |
7c673cae | 878 | * of commands submitted through this function. |
11fdf7f2 TL |
879 | * |
880 | * \param ctrlr Opaque handle to NVMe controller. | |
881 | * \param cmd NVM admin command to submit. | |
882 | * \param buf Virtual memory address of a single physically contiguous buffer. | |
883 | * \param len Size of buffer. | |
884 | * \param cb_fn Callback function invoked when the admin command completes. | |
885 | * \param cb_arg Argument passed to callback function. | |
886 | * | |
887 | * \return 0 on success, negated errno on failure. | |
7c673cae FG |
888 | */ |
889 | int spdk_nvme_ctrlr_cmd_admin_raw(struct spdk_nvme_ctrlr *ctrlr, | |
890 | struct spdk_nvme_cmd *cmd, | |
891 | void *buf, uint32_t len, | |
892 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
893 | ||
894 | /** | |
11fdf7f2 | 895 | * Process any outstanding completions for admin commands. |
7c673cae FG |
896 | * |
897 | * This will process completions for admin commands submitted on any thread. | |
898 | * | |
899 | * This call is non-blocking, i.e. it only processes completions that are ready | |
11fdf7f2 TL |
900 | * at the time of this function call. It does not wait for outstanding commands |
901 | * to finish. | |
7c673cae | 902 | * |
11fdf7f2 TL |
903 | * This function is thread safe and can be called at any point while the controller |
904 | * is attached to the SPDK NVMe driver. | |
7c673cae | 905 | * |
11fdf7f2 TL |
906 | * \param ctrlr Opaque handle to NVMe controller. |
907 | * | |
908 | * \return number of completions processed (may be 0) or negated on error. | |
7c673cae FG |
909 | */ |
910 | int32_t spdk_nvme_ctrlr_process_admin_completions(struct spdk_nvme_ctrlr *ctrlr); | |
911 | ||
912 | ||
11fdf7f2 TL |
913 | /** |
914 | * Opaque handle to a namespace. Obtained by calling spdk_nvme_ctrlr_get_ns(). | |
915 | */ | |
7c673cae FG |
916 | struct spdk_nvme_ns; |
917 | ||
918 | /** | |
11fdf7f2 TL |
919 | * Get a handle to a namespace for the given controller. |
920 | * | |
921 | * Namespaces are numbered from 1 to the total number of namespaces. There will | |
922 | * never be any gaps in the numbering. The number of namespaces is obtained by | |
923 | * calling spdk_nvme_ctrlr_get_num_ns(). | |
7c673cae | 924 | * |
11fdf7f2 TL |
925 | * This function is thread safe and can be called at any point while the controller |
926 | * is attached to the SPDK NVMe driver. | |
7c673cae | 927 | * |
11fdf7f2 TL |
928 | * \param ctrlr Opaque handle to NVMe controller. |
929 | * \param ns_id Namespace id. | |
930 | * | |
931 | * \return a pointer to the namespace. | |
7c673cae FG |
932 | */ |
933 | struct spdk_nvme_ns *spdk_nvme_ctrlr_get_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t ns_id); | |
934 | ||
935 | /** | |
11fdf7f2 | 936 | * Get a specific log page from the NVMe controller. |
7c673cae | 937 | * |
11fdf7f2 TL |
938 | * This function is thread safe and can be called at any point while the controller |
939 | * is attached to the SPDK NVMe driver. | |
940 | * | |
941 | * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of | |
942 | * commands submitted through this function. | |
943 | * | |
944 | * \sa spdk_nvme_ctrlr_is_log_page_supported() | |
945 | * | |
946 | * \param ctrlr Opaque handle to NVMe controller. | |
7c673cae | 947 | * \param log_page The log page identifier. |
11fdf7f2 TL |
948 | * \param nsid Depending on the log page, this may be 0, a namespace identifier, |
949 | * or SPDK_NVME_GLOBAL_NS_TAG. | |
7c673cae FG |
950 | * \param payload The pointer to the payload buffer. |
951 | * \param payload_size The size of payload buffer. | |
11fdf7f2 TL |
952 | * \param offset Offset in bytes within the log page to start retrieving log page |
953 | * data. May only be non-zero if the controller supports extended data for Get Log | |
954 | * Page as reported in the controller data log page attributes. | |
7c673cae FG |
955 | * \param cb_fn Callback function to invoke when the log page has been retrieved. |
956 | * \param cb_arg Argument to pass to the callback function. | |
957 | * | |
11fdf7f2 TL |
958 | * \return 0 if successfully submitted, negated errno if resources could not be |
959 | * allocated for this request. | |
7c673cae FG |
960 | */ |
961 | int spdk_nvme_ctrlr_cmd_get_log_page(struct spdk_nvme_ctrlr *ctrlr, | |
962 | uint8_t log_page, uint32_t nsid, | |
963 | void *payload, uint32_t payload_size, | |
964 | uint64_t offset, | |
965 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
966 | ||
967 | /** | |
11fdf7f2 TL |
968 | * Abort a specific previously-submitted NVMe command. |
969 | * | |
970 | * \sa spdk_nvme_ctrlr_register_timeout_callback() | |
7c673cae FG |
971 | * |
972 | * \param ctrlr NVMe controller to which the command was submitted. | |
11fdf7f2 TL |
973 | * \param qpair NVMe queue pair to which the command was submitted. For admin |
974 | * commands, pass NULL for the qpair. | |
7c673cae FG |
975 | * \param cid Command ID of the command to abort. |
976 | * \param cb_fn Callback function to invoke when the abort has completed. | |
11fdf7f2 | 977 | * \param cb_arg Argument to pass to the callback function. |
7c673cae FG |
978 | * |
979 | * \return 0 if successfully submitted, negated errno value otherwise. | |
7c673cae FG |
980 | */ |
981 | int spdk_nvme_ctrlr_cmd_abort(struct spdk_nvme_ctrlr *ctrlr, | |
982 | struct spdk_nvme_qpair *qpair, | |
983 | uint16_t cid, | |
984 | spdk_nvme_cmd_cb cb_fn, | |
985 | void *cb_arg); | |
986 | ||
987 | /** | |
11fdf7f2 TL |
988 | * Set specific feature for the given NVMe controller. |
989 | * | |
990 | * This function is thread safe and can be called at any point while the controller | |
991 | * is attached to the SPDK NVMe driver. | |
992 | * | |
993 | * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of | |
994 | * commands submitted through this function. | |
995 | * | |
996 | * \sa spdk_nvme_ctrlr_cmd_get_feature(). | |
7c673cae FG |
997 | * |
998 | * \param ctrlr NVMe controller to manipulate. | |
999 | * \param feature The feature identifier. | |
1000 | * \param cdw11 as defined by the specification for this command. | |
1001 | * \param cdw12 as defined by the specification for this command. | |
1002 | * \param payload The pointer to the payload buffer. | |
1003 | * \param payload_size The size of payload buffer. | |
1004 | * \param cb_fn Callback function to invoke when the feature has been set. | |
1005 | * \param cb_arg Argument to pass to the callback function. | |
1006 | * | |
11fdf7f2 TL |
1007 | * \return 0 if successfully submitted, negated errno if resources could not be |
1008 | * allocated for this request. | |
7c673cae FG |
1009 | */ |
1010 | int spdk_nvme_ctrlr_cmd_set_feature(struct spdk_nvme_ctrlr *ctrlr, | |
1011 | uint8_t feature, uint32_t cdw11, uint32_t cdw12, | |
1012 | void *payload, uint32_t payload_size, | |
1013 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
1014 | ||
1015 | /** | |
11fdf7f2 TL |
1016 | * Get specific feature from given NVMe controller. |
1017 | * | |
1018 | * This function is thread safe and can be called at any point while the controller | |
1019 | * is attached to the SPDK NVMe driver. | |
1020 | * | |
1021 | * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of | |
1022 | * commands submitted through this function. | |
1023 | * | |
1024 | * \sa spdk_nvme_ctrlr_cmd_set_feature() | |
7c673cae FG |
1025 | * |
1026 | * \param ctrlr NVMe controller to query. | |
1027 | * \param feature The feature identifier. | |
1028 | * \param cdw11 as defined by the specification for this command. | |
1029 | * \param payload The pointer to the payload buffer. | |
1030 | * \param payload_size The size of payload buffer. | |
1031 | * \param cb_fn Callback function to invoke when the feature has been retrieved. | |
1032 | * \param cb_arg Argument to pass to the callback function. | |
1033 | * | |
11fdf7f2 TL |
1034 | * \return 0 if successfully submitted, ENOMEM if resources could not be allocated |
1035 | * for this request. | |
7c673cae FG |
1036 | */ |
1037 | int spdk_nvme_ctrlr_cmd_get_feature(struct spdk_nvme_ctrlr *ctrlr, | |
1038 | uint8_t feature, uint32_t cdw11, | |
1039 | void *payload, uint32_t payload_size, | |
1040 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
1041 | ||
1042 | /** | |
11fdf7f2 | 1043 | * Get specific feature from given NVMe controller. |
7c673cae | 1044 | * |
11fdf7f2 TL |
1045 | * \param ctrlr NVMe controller to query. |
1046 | * \param feature The feature identifier. | |
1047 | * \param cdw11 as defined by the specification for this command. | |
1048 | * \param payload The pointer to the payload buffer. | |
1049 | * \param payload_size The size of payload buffer. | |
1050 | * \param cb_fn Callback function to invoke when the feature has been retrieved. | |
1051 | * \param cb_arg Argument to pass to the callback function. | |
1052 | * \param ns_id The namespace identifier. | |
7c673cae | 1053 | * |
11fdf7f2 TL |
1054 | * \return 0 if successfully submitted, ENOMEM if resources could not be allocated |
1055 | * for this request | |
7c673cae | 1056 | * |
11fdf7f2 TL |
1057 | * This function is thread safe and can be called at any point while the controller |
1058 | * is attached to the SPDK NVMe driver. | |
7c673cae FG |
1059 | * |
1060 | * Call \ref spdk_nvme_ctrlr_process_admin_completions() to poll for completion | |
1061 | * of commands submitted through this function. | |
11fdf7f2 TL |
1062 | * |
1063 | * \sa spdk_nvme_ctrlr_cmd_set_feature_ns() | |
7c673cae | 1064 | */ |
11fdf7f2 TL |
1065 | int spdk_nvme_ctrlr_cmd_get_feature_ns(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature, |
1066 | uint32_t cdw11, void *payload, uint32_t payload_size, | |
1067 | spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t ns_id); | |
7c673cae FG |
1068 | |
1069 | /** | |
11fdf7f2 | 1070 | * Set specific feature for the given NVMe controller and namespace ID. |
7c673cae | 1071 | * |
11fdf7f2 TL |
1072 | * \param ctrlr NVMe controller to manipulate. |
1073 | * \param feature The feature identifier. | |
1074 | * \param cdw11 as defined by the specification for this command. | |
1075 | * \param cdw12 as defined by the specification for this command. | |
1076 | * \param payload The pointer to the payload buffer. | |
1077 | * \param payload_size The size of payload buffer. | |
1078 | * \param cb_fn Callback function to invoke when the feature has been set. | |
1079 | * \param cb_arg Argument to pass to the callback function. | |
1080 | * \param ns_id The namespace identifier. | |
7c673cae | 1081 | * |
11fdf7f2 TL |
1082 | * \return 0 if successfully submitted, ENOMEM if resources could not be allocated |
1083 | * for this request. | |
7c673cae | 1084 | * |
11fdf7f2 TL |
1085 | * This function is thread safe and can be called at any point while the controller |
1086 | * is attached to the SPDK NVMe driver. | |
7c673cae FG |
1087 | * |
1088 | * Call \ref spdk_nvme_ctrlr_process_admin_completions() to poll for completion | |
1089 | * of commands submitted through this function. | |
11fdf7f2 TL |
1090 | * |
1091 | * \sa spdk_nvme_ctrlr_cmd_get_feature_ns() | |
7c673cae | 1092 | */ |
11fdf7f2 TL |
1093 | int spdk_nvme_ctrlr_cmd_set_feature_ns(struct spdk_nvme_ctrlr *ctrlr, uint8_t feature, |
1094 | uint32_t cdw11, uint32_t cdw12, void *payload, | |
1095 | uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, | |
1096 | void *cb_arg, uint32_t ns_id); | |
7c673cae FG |
1097 | |
1098 | /** | |
11fdf7f2 | 1099 | * Receive security protocol data from controller. |
7c673cae | 1100 | * |
11fdf7f2 | 1101 | * This function is thread safe and can be called at any point after spdk_nvme_probe(). |
7c673cae | 1102 | * |
11fdf7f2 TL |
1103 | * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of |
1104 | * commands submitted through this function. | |
1105 | * | |
1106 | * \param ctrlr NVMe controller to use for security receive command submission. | |
1107 | * \param secp Security Protocol that is used. | |
1108 | * \param spsp Security Protocol Specific field. | |
1109 | * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security | |
1110 | * Protocol EAh. | |
1111 | * \param payload The pointer to the payload buffer. | |
1112 | * \param payload_size The size of payload buffer. | |
1113 | * \param cb_fn Callback function to invoke when the security receive has completed. | |
1114 | * \param cb_arg Argument to pass to the callback function. | |
7c673cae | 1115 | * |
11fdf7f2 TL |
1116 | * \return 0 if successfully submitted, negated errno if resources could not be allocated |
1117 | * for this request. | |
7c673cae | 1118 | */ |
11fdf7f2 TL |
1119 | int spdk_nvme_ctrlr_cmd_security_receive(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp, uint16_t spsp, |
1120 | uint8_t nssf, void *payload, uint32_t payload_size, | |
1121 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
7c673cae FG |
1122 | |
1123 | /** | |
11fdf7f2 | 1124 | * Send security protocol data to controller. |
7c673cae | 1125 | * |
11fdf7f2 | 1126 | * This function is thread safe and can be called at any point after spdk_nvme_probe(). |
7c673cae | 1127 | * |
11fdf7f2 TL |
1128 | * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of |
1129 | * commands submitted through this function. | |
7c673cae | 1130 | * |
11fdf7f2 TL |
1131 | * \param ctrlr NVMe controller to use for security send command submission. |
1132 | * \param secp Security Protocol that is used. | |
1133 | * \param spsp Security Protocol Specific field. | |
1134 | * \param nssf NVMe Security Specific field. Indicate RPMB target when using Security | |
1135 | * Protocol EAh. | |
1136 | * \param payload The pointer to the payload buffer. | |
1137 | * \param payload_size The size of payload buffer. | |
1138 | * \param cb_fn Callback function to invoke when the security send has completed. | |
1139 | * \param cb_arg Argument to pass to the callback function. | |
7c673cae | 1140 | * |
11fdf7f2 TL |
1141 | * \return 0 if successfully submitted, negated errno if resources could not be allocated |
1142 | * for this request. | |
7c673cae | 1143 | */ |
11fdf7f2 TL |
1144 | int spdk_nvme_ctrlr_cmd_security_send(struct spdk_nvme_ctrlr *ctrlr, uint8_t secp, uint16_t spsp, |
1145 | uint8_t nssf, void *payload, uint32_t payload_size, | |
1146 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
7c673cae FG |
1147 | |
1148 | /** | |
11fdf7f2 | 1149 | * Attach the specified namespace to controllers. |
7c673cae | 1150 | * |
11fdf7f2 | 1151 | * This function is thread safe and can be called at any point after spdk_nvme_probe(). |
7c673cae | 1152 | * |
11fdf7f2 TL |
1153 | * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of |
1154 | * commands submitted through this function. | |
7c673cae | 1155 | * |
11fdf7f2 TL |
1156 | * \param ctrlr NVMe controller to use for command submission. |
1157 | * \param nsid Namespace identifier for namespace to attach. | |
1158 | * \param payload The pointer to the controller list. | |
7c673cae | 1159 | * |
11fdf7f2 TL |
1160 | * \return 0 if successfully submitted, ENOMEM if resources could not be allocated |
1161 | * for this request. | |
7c673cae | 1162 | */ |
11fdf7f2 TL |
1163 | int spdk_nvme_ctrlr_attach_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, |
1164 | struct spdk_nvme_ctrlr_list *payload); | |
7c673cae FG |
1165 | |
1166 | /** | |
11fdf7f2 | 1167 | * Detach the specified namespace from controllers. |
7c673cae | 1168 | * |
11fdf7f2 TL |
1169 | * This function is thread safe and can be called at any point after spdk_nvme_probe(). |
1170 | * | |
1171 | * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of | |
1172 | * commands submitted through this function. | |
1173 | * | |
1174 | * \param ctrlr NVMe controller to use for command submission. | |
1175 | * \param nsid Namespace ID to detach. | |
1176 | * \param payload The pointer to the controller list. | |
1177 | * | |
1178 | * \return 0 if successfully submitted, ENOMEM if resources could not be allocated | |
1179 | * for this request | |
1180 | */ | |
1181 | int spdk_nvme_ctrlr_detach_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, | |
1182 | struct spdk_nvme_ctrlr_list *payload); | |
1183 | ||
1184 | /** | |
1185 | * Create a namespace. | |
1186 | * | |
1187 | * This function is thread safe and can be called at any point after spdk_nvme_probe(). | |
1188 | * | |
1189 | * \param ctrlr NVMe controller to create namespace on. | |
1190 | * \param payload The pointer to the NVMe namespace data. | |
1191 | * | |
1192 | * \return Namespace ID (>= 1) if successfully created, or 0 if the request failed. | |
1193 | */ | |
1194 | uint32_t spdk_nvme_ctrlr_create_ns(struct spdk_nvme_ctrlr *ctrlr, | |
1195 | struct spdk_nvme_ns_data *payload); | |
1196 | ||
1197 | /** | |
1198 | * Delete a namespace. | |
1199 | * | |
1200 | * This function is thread safe and can be called at any point after spdk_nvme_probe(). | |
1201 | * | |
1202 | * Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of | |
1203 | * commands submitted through this function. | |
1204 | * | |
1205 | * \param ctrlr NVMe controller to delete namespace from. | |
1206 | * \param nsid The namespace identifier. | |
1207 | * | |
1208 | * \return 0 if successfully submitted, negated errno if resources could not be | |
1209 | * allocated | |
1210 | * for this request | |
1211 | */ | |
1212 | int spdk_nvme_ctrlr_delete_ns(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid); | |
1213 | ||
1214 | /** | |
1215 | * Format NVM. | |
1216 | * | |
1217 | * This function requests a low-level format of the media. | |
1218 | * | |
1219 | * This function is thread safe and can be called at any point after spdk_nvme_probe(). | |
1220 | * | |
1221 | * \param ctrlr NVMe controller to format. | |
1222 | * \param nsid The namespace identifier. May be SPDK_NVME_GLOBAL_NS_TAG to format | |
1223 | * all namespaces. | |
1224 | * \param format The format information for the command. | |
1225 | * | |
1226 | * \return 0 if successfully submitted, negated errno if resources could not be | |
1227 | * allocated for this request | |
1228 | */ | |
1229 | int spdk_nvme_ctrlr_format(struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, | |
1230 | struct spdk_nvme_format *format); | |
1231 | ||
1232 | /** | |
1233 | * Download a new firmware image. | |
1234 | * | |
1235 | * This function is thread safe and can be called at any point after spdk_nvme_probe(). | |
1236 | * | |
1237 | * \param ctrlr NVMe controller to perform firmware operation on. | |
7c673cae FG |
1238 | * \param payload The data buffer for the firmware image. |
1239 | * \param size The data size will be downloaded. | |
1240 | * \param slot The slot that the firmware image will be committed to. | |
11fdf7f2 TL |
1241 | * \param commit_action The action to perform when firmware is committed. |
1242 | * \param completion_status output parameter. Contains the completion status of | |
1243 | * the firmware commit operation. | |
7c673cae | 1244 | * |
11fdf7f2 TL |
1245 | * \return 0 if successfully submitted, ENOMEM if resources could not be allocated |
1246 | * for this request, -1 if the size is not multiple of 4. | |
7c673cae FG |
1247 | */ |
1248 | int spdk_nvme_ctrlr_update_firmware(struct spdk_nvme_ctrlr *ctrlr, void *payload, uint32_t size, | |
11fdf7f2 TL |
1249 | int slot, enum spdk_nvme_fw_commit_action commit_action, |
1250 | struct spdk_nvme_status *completion_status); | |
1251 | ||
1252 | /** | |
1253 | * Allocate an I/O buffer from the controller memory buffer (Experimental). | |
1254 | * | |
1255 | * This function allocates registered memory which belongs to the Controller | |
1256 | * Memory Buffer (CMB) of the specified NVMe controller. Note that the CMB has | |
1257 | * to support the WDS and RDS capabilities for the allocation to be successful. | |
1258 | * Also, due to vtophys contraints the CMB must be at least 4MiB in size. Free | |
1259 | * memory allocated with this function using spdk_nvme_ctrlr_free_cmb_io_buffer(). | |
1260 | * | |
1261 | * \param ctrlr Controller from which to allocate memory buffer. | |
1262 | * \param size Size of buffer to allocate in bytes. | |
1263 | * | |
1264 | * \return Pointer to controller memory buffer allocation, or NULL if allocation | |
1265 | * was not possible. | |
1266 | */ | |
1267 | void *spdk_nvme_ctrlr_alloc_cmb_io_buffer(struct spdk_nvme_ctrlr *ctrlr, size_t size); | |
7c673cae FG |
1268 | |
1269 | /** | |
11fdf7f2 TL |
1270 | * Free a controller memory I/O buffer (Experimental). |
1271 | * | |
1272 | * Note this function is currently a NOP which is one reason why this and | |
1273 | * spdk_nvme_ctrlr_alloc_cmb_io_buffer() are currently marked as experimental. | |
7c673cae | 1274 | * |
11fdf7f2 TL |
1275 | * \param ctrlr Controller from which the buffer was allocated. |
1276 | * \param buf Buffer previously allocated by spdk_nvme_ctrlr_alloc_cmb_io_buffer(). | |
1277 | * \param size Size of buf in bytes. | |
1278 | */ | |
1279 | void spdk_nvme_ctrlr_free_cmb_io_buffer(struct spdk_nvme_ctrlr *ctrlr, void *buf, size_t size); | |
1280 | ||
1281 | /** | |
1282 | * Get the identify namespace data as defined by the NVMe specification. | |
1283 | * | |
1284 | * This function is thread safe and can be called at any point while the controller | |
1285 | * is attached to the SPDK NVMe driver. | |
1286 | * | |
1287 | * \param ns Namespace. | |
1288 | * | |
1289 | * \return a pointer to the namespace data. | |
7c673cae FG |
1290 | */ |
1291 | const struct spdk_nvme_ns_data *spdk_nvme_ns_get_data(struct spdk_nvme_ns *ns); | |
1292 | ||
1293 | /** | |
11fdf7f2 TL |
1294 | * Get the namespace id (index number) from the given namespace handle. |
1295 | * | |
1296 | * This function is thread safe and can be called at any point while the controller | |
1297 | * is attached to the SPDK NVMe driver. | |
1298 | * | |
1299 | * \param ns Namespace. | |
7c673cae | 1300 | * |
11fdf7f2 | 1301 | * \return namespace id. |
7c673cae FG |
1302 | */ |
1303 | uint32_t spdk_nvme_ns_get_id(struct spdk_nvme_ns *ns); | |
1304 | ||
1305 | /** | |
11fdf7f2 TL |
1306 | * Get the controller with which this namespace is associated. |
1307 | * | |
1308 | * This function is thread safe and can be called at any point while the controller | |
1309 | * is attached to the SPDK NVMe driver. | |
1310 | * | |
1311 | * \param ns Namespace. | |
1312 | * | |
1313 | * \return a pointer to the controller. | |
1314 | */ | |
1315 | struct spdk_nvme_ctrlr *spdk_nvme_ns_get_ctrlr(struct spdk_nvme_ns *ns); | |
1316 | ||
1317 | /** | |
1318 | * Determine whether a namespace is active. | |
7c673cae FG |
1319 | * |
1320 | * Inactive namespaces cannot be the target of I/O commands. | |
11fdf7f2 TL |
1321 | * |
1322 | * \param ns Namespace to query. | |
1323 | * | |
1324 | * \return true if active, or false if inactive. | |
7c673cae FG |
1325 | */ |
1326 | bool spdk_nvme_ns_is_active(struct spdk_nvme_ns *ns); | |
1327 | ||
1328 | /** | |
11fdf7f2 TL |
1329 | * Get the maximum transfer size, in bytes, for an I/O sent to the given namespace. |
1330 | * | |
1331 | * This function is thread safe and can be called at any point while the controller | |
1332 | * is attached to the SPDK NVMe driver. | |
1333 | * | |
1334 | * \param ns Namespace to query. | |
7c673cae | 1335 | * |
11fdf7f2 | 1336 | * \return the maximum transfer size in bytes. |
7c673cae FG |
1337 | */ |
1338 | uint32_t spdk_nvme_ns_get_max_io_xfer_size(struct spdk_nvme_ns *ns); | |
1339 | ||
1340 | /** | |
11fdf7f2 TL |
1341 | * Get the sector size, in bytes, of the given namespace. |
1342 | * | |
1343 | * This function returns the size of the data sector only. It does not | |
1344 | * include metadata size. | |
1345 | * | |
1346 | * This function is thread safe and can be called at any point while the controller | |
1347 | * is attached to the SPDK NVMe driver. | |
7c673cae | 1348 | * |
11fdf7f2 TL |
1349 | * \param ns Namespace to query. |
1350 | * | |
1351 | * /return the sector size in bytes. | |
7c673cae FG |
1352 | */ |
1353 | uint32_t spdk_nvme_ns_get_sector_size(struct spdk_nvme_ns *ns); | |
1354 | ||
1355 | /** | |
11fdf7f2 TL |
1356 | * Get the extended sector size, in bytes, of the given namespace. |
1357 | * | |
1358 | * This function returns the size of the data sector plus metadata. | |
1359 | * | |
1360 | * This function is thread safe and can be called at any point while the controller | |
1361 | * is attached to the SPDK NVMe driver. | |
1362 | * | |
1363 | * \param ns Namespace to query. | |
7c673cae | 1364 | * |
11fdf7f2 TL |
1365 | * /return the extended sector size in bytes. |
1366 | */ | |
1367 | uint32_t spdk_nvme_ns_get_extended_sector_size(struct spdk_nvme_ns *ns); | |
1368 | ||
1369 | /** | |
1370 | * Get the number of sectors for the given namespace. | |
1371 | * | |
1372 | * This function is thread safe and can be called at any point while the controller | |
1373 | * is attached to the SPDK NVMe driver. | |
1374 | * | |
1375 | * \param ns Namespace to query. | |
1376 | * | |
1377 | * \return the number of sectors. | |
7c673cae FG |
1378 | */ |
1379 | uint64_t spdk_nvme_ns_get_num_sectors(struct spdk_nvme_ns *ns); | |
1380 | ||
1381 | /** | |
11fdf7f2 TL |
1382 | * Get the size, in bytes, of the given namespace. |
1383 | * | |
1384 | * This function is thread safe and can be called at any point while the controller | |
1385 | * is attached to the SPDK NVMe driver. | |
1386 | * | |
1387 | * \param ns Namespace to query. | |
7c673cae | 1388 | * |
11fdf7f2 | 1389 | * \return the size of the given namespace in bytes. |
7c673cae FG |
1390 | */ |
1391 | uint64_t spdk_nvme_ns_get_size(struct spdk_nvme_ns *ns); | |
1392 | ||
1393 | /** | |
11fdf7f2 TL |
1394 | * Get the end-to-end data protection information type of the given namespace. |
1395 | * | |
1396 | * This function is thread safe and can be called at any point while the controller | |
1397 | * is attached to the SPDK NVMe driver. | |
1398 | * | |
1399 | * \param ns Namespace to query. | |
7c673cae | 1400 | * |
11fdf7f2 | 1401 | * \return the end-to-end data protection information type. |
7c673cae FG |
1402 | */ |
1403 | enum spdk_nvme_pi_type spdk_nvme_ns_get_pi_type(struct spdk_nvme_ns *ns); | |
1404 | ||
1405 | /** | |
11fdf7f2 | 1406 | * Get the metadata size, in bytes, of the given namespace. |
7c673cae | 1407 | * |
11fdf7f2 TL |
1408 | * This function is thread safe and can be called at any point while the controller |
1409 | * is attached to the SPDK NVMe driver. | |
1410 | * | |
1411 | * \param ns Namespace to query. | |
1412 | * | |
1413 | * \return the metadata size of the given namespace in bytes. | |
7c673cae FG |
1414 | */ |
1415 | uint32_t spdk_nvme_ns_get_md_size(struct spdk_nvme_ns *ns); | |
1416 | ||
1417 | /** | |
11fdf7f2 TL |
1418 | * Check whether if the namespace can support extended LBA when end-to-end data |
1419 | * protection enabled. | |
1420 | * | |
1421 | * This function is thread safe and can be called at any point while the controller | |
1422 | * is attached to the SPDK NVMe driver. | |
7c673cae | 1423 | * |
11fdf7f2 TL |
1424 | * \param ns Namespace to query. |
1425 | * | |
1426 | * \return true if the namespace can support extended LBA when end-to-end data | |
1427 | * protection enabled, or false otherwise. | |
7c673cae FG |
1428 | */ |
1429 | bool spdk_nvme_ns_supports_extended_lba(struct spdk_nvme_ns *ns); | |
1430 | ||
11fdf7f2 TL |
1431 | /** |
1432 | * Determine the value returned when reading deallocated blocks. | |
1433 | * | |
1434 | * If deallocated blocks return 0, the deallocate command can be used as a more | |
1435 | * efficient alternative to the write_zeroes command, especially for large requests. | |
1436 | * | |
1437 | * \param ns Namespace. | |
1438 | * | |
1439 | * \return the logical block read value. | |
1440 | */ | |
1441 | enum spdk_nvme_dealloc_logical_block_read_value spdk_nvme_ns_get_dealloc_logical_block_read_value( | |
1442 | struct spdk_nvme_ns *ns); | |
1443 | ||
1444 | /** | |
1445 | * Get the optimal I/O boundary, in blocks, for the given namespace. | |
1446 | * | |
1447 | * Read and write commands should not cross the optimal I/O boundary for best | |
1448 | * performance. | |
1449 | * | |
1450 | * \param ns Namespace to query. | |
1451 | * | |
1452 | * \return Optimal granularity of I/O commands, in blocks, or 0 if no optimal | |
1453 | * granularity is reported. | |
1454 | */ | |
1455 | uint32_t spdk_nvme_ns_get_optimal_io_boundary(struct spdk_nvme_ns *ns); | |
1456 | ||
1457 | /** | |
1458 | * Get the UUID for the given namespace. | |
1459 | * | |
1460 | * \param ns Namespace to query. | |
1461 | * | |
1462 | * \return a pointer to namespace UUID, or NULL if ns does not have a UUID. | |
1463 | */ | |
1464 | const struct spdk_uuid *spdk_nvme_ns_get_uuid(const struct spdk_nvme_ns *ns); | |
1465 | ||
7c673cae FG |
1466 | /** |
1467 | * \brief Namespace command support flags. | |
1468 | */ | |
1469 | enum spdk_nvme_ns_flags { | |
1470 | SPDK_NVME_NS_DEALLOCATE_SUPPORTED = 0x1, /**< The deallocate command is supported */ | |
1471 | SPDK_NVME_NS_FLUSH_SUPPORTED = 0x2, /**< The flush command is supported */ | |
1472 | SPDK_NVME_NS_RESERVATION_SUPPORTED = 0x4, /**< The reservation command is supported */ | |
1473 | SPDK_NVME_NS_WRITE_ZEROES_SUPPORTED = 0x8, /**< The write zeroes command is supported */ | |
1474 | SPDK_NVME_NS_DPS_PI_SUPPORTED = 0x10, /**< The end-to-end data protection is supported */ | |
1475 | SPDK_NVME_NS_EXTENDED_LBA_SUPPORTED = 0x20, /**< The extended lba format is supported, | |
1476 | metadata is transferred as a contiguous | |
1477 | part of the logical block that it is associated with */ | |
1478 | }; | |
1479 | ||
1480 | /** | |
11fdf7f2 | 1481 | * Get the flags for the given namespace. |
7c673cae FG |
1482 | * |
1483 | * See spdk_nvme_ns_flags for the possible flags returned. | |
1484 | * | |
11fdf7f2 TL |
1485 | * This function is thread safe and can be called at any point while the controller |
1486 | * is attached to the SPDK NVMe driver. | |
1487 | * | |
1488 | * \param ns Namespace to query. | |
1489 | * | |
1490 | * \return the flags for the given namespace. | |
7c673cae FG |
1491 | */ |
1492 | uint32_t spdk_nvme_ns_get_flags(struct spdk_nvme_ns *ns); | |
1493 | ||
1494 | /** | |
1495 | * Restart the SGL walk to the specified offset when the command has scattered payloads. | |
1496 | * | |
11fdf7f2 TL |
1497 | * \param cb_arg Argument passed to readv/writev. |
1498 | * \param offset Offset for SGL. | |
7c673cae FG |
1499 | */ |
1500 | typedef void (*spdk_nvme_req_reset_sgl_cb)(void *cb_arg, uint32_t offset); | |
1501 | ||
1502 | /** | |
1503 | * Fill out *address and *length with the current SGL entry and advance to the next | |
1504 | * entry for the next time the callback is invoked. | |
1505 | * | |
11fdf7f2 TL |
1506 | * The described segment must be physically contiguous. |
1507 | * | |
1508 | * \param cb_arg Argument passed to readv/writev. | |
1509 | * \param address Virtual address of this segment. | |
1510 | * \param length Length of this physical segment. | |
7c673cae FG |
1511 | */ |
1512 | typedef int (*spdk_nvme_req_next_sge_cb)(void *cb_arg, void **address, uint32_t *length); | |
1513 | ||
1514 | /** | |
11fdf7f2 | 1515 | * Submit a write I/O to the specified NVMe namespace. |
7c673cae FG |
1516 | * |
1517 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
1518 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1519 | * given time. | |
1520 | * | |
1521 | * \param ns NVMe namespace to submit the write I/O. | |
1522 | * \param qpair I/O queue pair to submit the request. | |
1523 | * \param payload Virtual address pointer to the data payload. | |
1524 | * \param lba Starting LBA to write the data. | |
1525 | * \param lba_count Length (in sectors) for the write operation. | |
1526 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1527 | * \param cb_arg Argument to pass to the callback function. | |
1528 | * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in | |
1529 | * spdk/nvme_spec.h, for this I/O. | |
1530 | * | |
1531 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1532 | * cannot be allocated for the I/O request | |
7c673cae FG |
1533 | */ |
1534 | int spdk_nvme_ns_cmd_write(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, | |
1535 | uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, | |
1536 | void *cb_arg, uint32_t io_flags); | |
1537 | ||
1538 | /** | |
11fdf7f2 | 1539 | * Submit a write I/O to the specified NVMe namespace. |
7c673cae FG |
1540 | * |
1541 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
1542 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1543 | * given time. | |
1544 | * | |
1545 | * \param ns NVMe namespace to submit the write I/O. | |
1546 | * \param qpair I/O queue pair to submit the request. | |
1547 | * \param lba Starting LBA to write the data. | |
1548 | * \param lba_count Length (in sectors) for the write operation. | |
1549 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1550 | * \param cb_arg Argument to pass to the callback function. | |
1551 | * \param io_flags Set flags, defined in nvme_spec.h, for this I/O. | |
1552 | * \param reset_sgl_fn Callback function to reset scattered payload. | |
1553 | * \param next_sge_fn Callback function to iterate each scattered payload memory | |
1554 | * segment. | |
1555 | * | |
1556 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1557 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1558 | */ |
1559 | int spdk_nvme_ns_cmd_writev(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, | |
1560 | uint64_t lba, uint32_t lba_count, | |
1561 | spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, | |
1562 | spdk_nvme_req_reset_sgl_cb reset_sgl_fn, | |
1563 | spdk_nvme_req_next_sge_cb next_sge_fn); | |
1564 | ||
1565 | /** | |
11fdf7f2 TL |
1566 | * Submit a write I/O to the specified NVMe namespace. |
1567 | * | |
1568 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
1569 | * The user must ensure that only one thread submits I/O on a given qpair at any | |
1570 | * given time. | |
7c673cae FG |
1571 | * |
1572 | * \param ns NVMe namespace to submit the write I/O | |
1573 | * \param qpair I/O queue pair to submit the request | |
7c673cae FG |
1574 | * \param lba starting LBA to write the data |
1575 | * \param lba_count length (in sectors) for the write operation | |
1576 | * \param cb_fn callback function to invoke when the I/O is completed | |
1577 | * \param cb_arg argument to pass to the callback function | |
11fdf7f2 TL |
1578 | * \param io_flags set flags, defined in nvme_spec.h, for this I/O |
1579 | * \param reset_sgl_fn callback function to reset scattered payload | |
1580 | * \param next_sge_fn callback function to iterate each scattered | |
1581 | * payload memory segment | |
1582 | * \param metadata virtual address pointer to the metadata payload, the length | |
1583 | * of metadata is specified by spdk_nvme_ns_get_md_size() | |
7c673cae FG |
1584 | * \param apptag_mask application tag mask. |
1585 | * \param apptag application tag to use end-to-end protection information. | |
1586 | * | |
11fdf7f2 TL |
1587 | * \return 0 if successfully submitted, ENOMEM if an nvme_request structure |
1588 | * cannot be allocated for the I/O request. | |
1589 | */ | |
1590 | int spdk_nvme_ns_cmd_writev_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, | |
1591 | uint64_t lba, uint32_t lba_count, | |
1592 | spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, | |
1593 | spdk_nvme_req_reset_sgl_cb reset_sgl_fn, | |
1594 | spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata, | |
1595 | uint16_t apptag_mask, uint16_t apptag); | |
1596 | ||
1597 | /** | |
1598 | * Submit a write I/O to the specified NVMe namespace. | |
7c673cae FG |
1599 | * |
1600 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
1601 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1602 | * given time. | |
1603 | * | |
1604 | * \param ns NVMe namespace to submit the write I/O. | |
1605 | * \param qpair I/O queue pair to submit the request. | |
1606 | * \param payload Virtual address pointer to the data payload. | |
1607 | * \param metadata Virtual address pointer to the metadata payload, the length | |
1608 | * of metadata is specified by spdk_nvme_ns_get_md_size(). | |
1609 | * \param lba Starting LBA to write the data. | |
1610 | * \param lba_count Length (in sectors) for the write operation. | |
1611 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1612 | * \param cb_arg Argument to pass to the callback function. | |
1613 | * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in | |
1614 | * spdk/nvme_spec.h, for this I/O. | |
1615 | * \param apptag_mask Application tag mask. | |
1616 | * \param apptag Application tag to use end-to-end protection information. | |
1617 | * | |
1618 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1619 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1620 | */ |
1621 | int spdk_nvme_ns_cmd_write_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, | |
1622 | void *payload, void *metadata, | |
1623 | uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, | |
1624 | void *cb_arg, uint32_t io_flags, | |
1625 | uint16_t apptag_mask, uint16_t apptag); | |
1626 | ||
1627 | /** | |
11fdf7f2 | 1628 | * Submit a write zeroes I/O to the specified NVMe namespace. |
7c673cae FG |
1629 | * |
1630 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
1631 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1632 | * given time. | |
1633 | * | |
1634 | * \param ns NVMe namespace to submit the write zeroes I/O. | |
1635 | * \param qpair I/O queue pair to submit the request. | |
1636 | * \param lba Starting LBA for this command. | |
1637 | * \param lba_count Length (in sectors) for the write zero operation. | |
1638 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1639 | * \param cb_arg Argument to pass to the callback function. | |
1640 | * \param io_flags Set flags, defined by the SPDK_NVME_IO_FLAGS_* entries in | |
1641 | * spdk/nvme_spec.h, for this I/O. | |
1642 | * | |
1643 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1644 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1645 | */ |
1646 | int spdk_nvme_ns_cmd_write_zeroes(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, | |
1647 | uint64_t lba, uint32_t lba_count, | |
1648 | spdk_nvme_cmd_cb cb_fn, void *cb_arg, | |
1649 | uint32_t io_flags); | |
1650 | ||
1651 | /** | |
1652 | * \brief Submits a read I/O to the specified NVMe namespace. | |
1653 | * | |
7c673cae | 1654 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). |
11fdf7f2 TL |
1655 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1656 | * given time. | |
1657 | * | |
1658 | * \param ns NVMe namespace to submit the read I/O. | |
1659 | * \param qpair I/O queue pair to submit the request. | |
1660 | * \param payload Virtual address pointer to the data payload. | |
1661 | * \param lba Starting LBA to read the data. | |
1662 | * \param lba_count Length (in sectors) for the read operation. | |
1663 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1664 | * \param cb_arg Argument to pass to the callback function. | |
1665 | * \param io_flags Set flags, defined in nvme_spec.h, for this I/O. | |
1666 | * | |
1667 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1668 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1669 | */ |
1670 | int spdk_nvme_ns_cmd_read(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, | |
1671 | uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, | |
1672 | void *cb_arg, uint32_t io_flags); | |
1673 | ||
1674 | /** | |
11fdf7f2 | 1675 | * Submit a read I/O to the specified NVMe namespace. |
7c673cae FG |
1676 | * |
1677 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
1678 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1679 | * given time. | |
1680 | * | |
1681 | * \param ns NVMe namespace to submit the read I/O. | |
1682 | * \param qpair I/O queue pair to submit the request. | |
1683 | * \param lba Starting LBA to read the data. | |
1684 | * \param lba_count Length (in sectors) for the read operation. | |
1685 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1686 | * \param cb_arg Argument to pass to the callback function. | |
1687 | * \param io_flags Set flags, defined in nvme_spec.h, for this I/O. | |
1688 | * \param reset_sgl_fn Callback function to reset scattered payload. | |
1689 | * \param next_sge_fn Callback function to iterate each scattered payload memory | |
1690 | * segment. | |
1691 | * | |
1692 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1693 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1694 | */ |
1695 | int spdk_nvme_ns_cmd_readv(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, | |
1696 | uint64_t lba, uint32_t lba_count, | |
1697 | spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, | |
1698 | spdk_nvme_req_reset_sgl_cb reset_sgl_fn, | |
1699 | spdk_nvme_req_next_sge_cb next_sge_fn); | |
1700 | ||
1701 | /** | |
11fdf7f2 | 1702 | * Submit a read I/O to the specified NVMe namespace. |
7c673cae FG |
1703 | * |
1704 | * \param ns NVMe namespace to submit the read I/O | |
1705 | * \param qpair I/O queue pair to submit the request | |
7c673cae FG |
1706 | * \param lba starting LBA to read the data |
1707 | * \param lba_count length (in sectors) for the read operation | |
1708 | * \param cb_fn callback function to invoke when the I/O is completed | |
1709 | * \param cb_arg argument to pass to the callback function | |
1710 | * \param io_flags set flags, defined in nvme_spec.h, for this I/O | |
11fdf7f2 TL |
1711 | * \param reset_sgl_fn callback function to reset scattered payload |
1712 | * \param next_sge_fn callback function to iterate each scattered | |
1713 | * payload memory segment | |
1714 | * \param metadata virtual address pointer to the metadata payload, the length | |
1715 | * of metadata is specified by spdk_nvme_ns_get_md_size() | |
7c673cae FG |
1716 | * \param apptag_mask application tag mask. |
1717 | * \param apptag application tag to use end-to-end protection information. | |
1718 | * | |
1719 | * \return 0 if successfully submitted, ENOMEM if an nvme_request | |
1720 | * structure cannot be allocated for the I/O request | |
1721 | * | |
1722 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
1723 | * The user must ensure that only one thread submits I/O on a given qpair at any given time. | |
1724 | */ | |
11fdf7f2 TL |
1725 | int spdk_nvme_ns_cmd_readv_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, |
1726 | uint64_t lba, uint32_t lba_count, | |
1727 | spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, | |
1728 | spdk_nvme_req_reset_sgl_cb reset_sgl_fn, | |
1729 | spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata, | |
1730 | uint16_t apptag_mask, uint16_t apptag); | |
1731 | ||
1732 | /** | |
1733 | * Submits a read I/O to the specified NVMe namespace. | |
1734 | * | |
1735 | * \param ns NVMe namespace to submit the read I/O | |
1736 | * \param qpair I/O queue pair to submit the request | |
1737 | * \param payload virtual address pointer to the data payload | |
1738 | * \param metadata virtual address pointer to the metadata payload, the length | |
1739 | * of metadata is specified by spdk_nvme_ns_get_md_size(). | |
1740 | * \param lba starting LBA to read the data. | |
1741 | * \param lba_count Length (in sectors) for the read operation. | |
1742 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1743 | * \param cb_arg Argument to pass to the callback function. | |
1744 | * \param io_flags Set flags, defined in nvme_spec.h, for this I/O. | |
1745 | * \param apptag_mask Application tag mask. | |
1746 | * \param apptag Application tag to use end-to-end protection information. | |
1747 | * | |
1748 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1749 | * cannot be allocated for the I/O request. | |
1750 | */ | |
7c673cae FG |
1751 | int spdk_nvme_ns_cmd_read_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, |
1752 | void *payload, void *metadata, | |
1753 | uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, | |
1754 | void *cb_arg, uint32_t io_flags, | |
1755 | uint16_t apptag_mask, uint16_t apptag); | |
1756 | ||
1757 | /** | |
11fdf7f2 TL |
1758 | * Submit a data set management request to the specified NVMe namespace. Data set |
1759 | * management operations are designed to optimize interaction with the block | |
1760 | * translation layer inside the device. The most common type of operation is | |
1761 | * deallocate, which is often referred to as TRIM or UNMAP. | |
1762 | * | |
1763 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
1764 | * The user must ensure that only one thread submits I/O on a given qpair at any | |
1765 | * given time. | |
1766 | * | |
1767 | * This is a convenience wrapper that will automatically allocate and construct | |
1768 | * the correct data buffers. Therefore, ranges does not need to be allocated from | |
1769 | * pinned memory and can be placed on the stack. If a higher performance, zero-copy | |
1770 | * version of DSM is required, simply build and submit a raw command using | |
1771 | * spdk_nvme_ctrlr_cmd_io_raw(). | |
7c673cae FG |
1772 | * |
1773 | * \param ns NVMe namespace to submit the DSM request | |
11fdf7f2 | 1774 | * \param type A bit field constructed from \ref spdk_nvme_dsm_attribute. |
7c673cae | 1775 | * \param qpair I/O queue pair to submit the request |
11fdf7f2 TL |
1776 | * \param ranges An array of \ref spdk_nvme_dsm_range elements describing the LBAs |
1777 | * to operate on. | |
7c673cae | 1778 | * \param num_ranges The number of elements in the ranges array. |
11fdf7f2 TL |
1779 | * \param cb_fn Callback function to invoke when the I/O is completed |
1780 | * \param cb_arg Argument to pass to the callback function | |
7c673cae FG |
1781 | * |
1782 | * \return 0 if successfully submitted, negated POSIX errno values otherwise. | |
7c673cae FG |
1783 | */ |
1784 | int spdk_nvme_ns_cmd_dataset_management(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, | |
1785 | uint32_t type, | |
1786 | const struct spdk_nvme_dsm_range *ranges, | |
1787 | uint16_t num_ranges, | |
1788 | spdk_nvme_cmd_cb cb_fn, | |
1789 | void *cb_arg); | |
1790 | ||
1791 | /** | |
11fdf7f2 | 1792 | * Submit a flush request to the specified NVMe namespace. |
7c673cae | 1793 | * |
11fdf7f2 TL |
1794 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). |
1795 | * The user must ensure that only one thread submits I/O on a given qpair at any | |
1796 | * given time. | |
7c673cae | 1797 | * |
11fdf7f2 TL |
1798 | * \param ns NVMe namespace to submit the flush request. |
1799 | * \param qpair I/O queue pair to submit the request. | |
1800 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1801 | * \param cb_arg Argument to pass to the callback function. | |
7c673cae | 1802 | * |
11fdf7f2 TL |
1803 | * \return 0 if successfully submitted, negated errno if an nvme_request structure |
1804 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1805 | */ |
1806 | int spdk_nvme_ns_cmd_flush(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, | |
1807 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
1808 | ||
1809 | /** | |
11fdf7f2 | 1810 | * Submit a reservation register to the specified NVMe namespace. |
7c673cae FG |
1811 | * |
1812 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
1813 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1814 | * given time. | |
1815 | * | |
1816 | * \param ns NVMe namespace to submit the reservation register request. | |
1817 | * \param qpair I/O queue pair to submit the request. | |
1818 | * \param payload Virtual address pointer to the reservation register data. | |
1819 | * \param ignore_key '1' the current reservation key check is disabled. | |
1820 | * \param action Specifies the registration action. | |
1821 | * \param cptpl Change the Persist Through Power Loss state. | |
1822 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1823 | * \param cb_arg Argument to pass to the callback function. | |
1824 | * | |
1825 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1826 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1827 | */ |
1828 | int spdk_nvme_ns_cmd_reservation_register(struct spdk_nvme_ns *ns, | |
1829 | struct spdk_nvme_qpair *qpair, | |
1830 | struct spdk_nvme_reservation_register_data *payload, | |
1831 | bool ignore_key, | |
1832 | enum spdk_nvme_reservation_register_action action, | |
1833 | enum spdk_nvme_reservation_register_cptpl cptpl, | |
1834 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
1835 | ||
1836 | /** | |
11fdf7f2 | 1837 | * Submits a reservation release to the specified NVMe namespace. |
7c673cae FG |
1838 | * |
1839 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
1840 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1841 | * given time. | |
1842 | * | |
1843 | * \param ns NVMe namespace to submit the reservation release request. | |
1844 | * \param qpair I/O queue pair to submit the request. | |
1845 | * \param payload Virtual address pointer to current reservation key. | |
1846 | * \param ignore_key '1' the current reservation key check is disabled. | |
1847 | * \param action Specifies the reservation release action. | |
1848 | * \param type Reservation type for the namespace. | |
1849 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1850 | * \param cb_arg Argument to pass to the callback function. | |
1851 | * | |
1852 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1853 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1854 | */ |
1855 | int spdk_nvme_ns_cmd_reservation_release(struct spdk_nvme_ns *ns, | |
1856 | struct spdk_nvme_qpair *qpair, | |
1857 | struct spdk_nvme_reservation_key_data *payload, | |
1858 | bool ignore_key, | |
1859 | enum spdk_nvme_reservation_release_action action, | |
1860 | enum spdk_nvme_reservation_type type, | |
1861 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
1862 | ||
1863 | /** | |
11fdf7f2 | 1864 | * Submits a reservation acquire to the specified NVMe namespace. |
7c673cae FG |
1865 | * |
1866 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
1867 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1868 | * given time. | |
1869 | * | |
1870 | * \param ns NVMe namespace to submit the reservation acquire request. | |
1871 | * \param qpair I/O queue pair to submit the request. | |
1872 | * \param payload Virtual address pointer to reservation acquire data. | |
1873 | * \param ignore_key '1' the current reservation key check is disabled. | |
1874 | * \param action Specifies the reservation acquire action. | |
1875 | * \param type Reservation type for the namespace. | |
1876 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1877 | * \param cb_arg Argument to pass to the callback function. | |
1878 | * | |
1879 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1880 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1881 | */ |
1882 | int spdk_nvme_ns_cmd_reservation_acquire(struct spdk_nvme_ns *ns, | |
1883 | struct spdk_nvme_qpair *qpair, | |
1884 | struct spdk_nvme_reservation_acquire_data *payload, | |
1885 | bool ignore_key, | |
1886 | enum spdk_nvme_reservation_acquire_action action, | |
1887 | enum spdk_nvme_reservation_type type, | |
1888 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
1889 | ||
1890 | /** | |
11fdf7f2 | 1891 | * Submit a reservation report to the specified NVMe namespace. |
7c673cae FG |
1892 | * |
1893 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
11fdf7f2 TL |
1894 | * The user must ensure that only one thread submits I/O on a given qpair at any |
1895 | * given time. | |
1896 | * | |
1897 | * \param ns NVMe namespace to submit the reservation report request. | |
1898 | * \param qpair I/O queue pair to submit the request. | |
1899 | * \param payload Virtual address pointer for reservation status data. | |
1900 | * \param len Length bytes for reservation status data structure. | |
1901 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1902 | * \param cb_arg Argument to pass to the callback function. | |
1903 | * | |
1904 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1905 | * cannot be allocated for the I/O request. | |
7c673cae FG |
1906 | */ |
1907 | int spdk_nvme_ns_cmd_reservation_report(struct spdk_nvme_ns *ns, | |
1908 | struct spdk_nvme_qpair *qpair, | |
1909 | void *payload, uint32_t len, | |
1910 | spdk_nvme_cmd_cb cb_fn, void *cb_arg); | |
1911 | ||
11fdf7f2 TL |
1912 | /** |
1913 | * Submit a compare I/O to the specified NVMe namespace. | |
1914 | * | |
1915 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
1916 | * The user must ensure that only one thread submits I/O on a given qpair at any | |
1917 | * given time. | |
1918 | * | |
1919 | * \param ns NVMe namespace to submit the compare I/O. | |
1920 | * \param qpair I/O queue pair to submit the request. | |
1921 | * \param payload Virtual address pointer to the data payload. | |
1922 | * \param lba Starting LBA to compare the data. | |
1923 | * \param lba_count Length (in sectors) for the compare operation. | |
1924 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1925 | * \param cb_arg Argument to pass to the callback function. | |
1926 | * \param io_flags Set flags, defined in nvme_spec.h, for this I/O. | |
1927 | * | |
1928 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1929 | * cannot be allocated for the I/O request. | |
1930 | */ | |
1931 | int spdk_nvme_ns_cmd_compare(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, | |
1932 | uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, | |
1933 | void *cb_arg, uint32_t io_flags); | |
1934 | ||
1935 | /** | |
1936 | * Submit a compare I/O to the specified NVMe namespace. | |
1937 | * | |
1938 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
1939 | * The user must ensure that only one thread submits I/O on a given qpair at any | |
1940 | * given time. | |
1941 | * | |
1942 | * \param ns NVMe namespace to submit the compare I/O. | |
1943 | * \param qpair I/O queue pair to submit the request. | |
1944 | * \param lba Starting LBA to compare the data. | |
1945 | * \param lba_count Length (in sectors) for the compare operation. | |
1946 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1947 | * \param cb_arg Argument to pass to the callback function. | |
1948 | * \param io_flags Set flags, defined in nvme_spec.h, for this I/O. | |
1949 | * \param reset_sgl_fn Callback function to reset scattered payload. | |
1950 | * \param next_sge_fn Callback function to iterate each scattered payload memory | |
1951 | * segment. | |
1952 | * | |
1953 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1954 | * cannot be allocated for the I/O request. | |
1955 | */ | |
1956 | int spdk_nvme_ns_cmd_comparev(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, | |
1957 | uint64_t lba, uint32_t lba_count, | |
1958 | spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, | |
1959 | spdk_nvme_req_reset_sgl_cb reset_sgl_fn, | |
1960 | spdk_nvme_req_next_sge_cb next_sge_fn); | |
1961 | ||
1962 | /** | |
1963 | * Submit a compare I/O to the specified NVMe namespace. | |
1964 | * | |
1965 | * The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). | |
1966 | * The user must ensure that only one thread submits I/O on a given qpair at any | |
1967 | * given time. | |
1968 | * | |
1969 | * \param ns NVMe namespace to submit the compare I/O. | |
1970 | * \param qpair I/O queue pair to submit the request. | |
1971 | * \param payload Virtual address pointer to the data payload. | |
1972 | * \param metadata Virtual address pointer to the metadata payload, the length | |
1973 | * of metadata is specified by spdk_nvme_ns_get_md_size(). | |
1974 | * \param lba Starting LBA to compare the data. | |
1975 | * \param lba_count Length (in sectors) for the compare operation. | |
1976 | * \param cb_fn Callback function to invoke when the I/O is completed. | |
1977 | * \param cb_arg Argument to pass to the callback function. | |
1978 | * \param io_flags Set flags, defined in nvme_spec.h, for this I/O. | |
1979 | * \param apptag_mask Application tag mask. | |
1980 | * \param apptag Application tag to use end-to-end protection information. | |
1981 | * | |
1982 | * \return 0 if successfully submitted, negated errno if an nvme_request structure | |
1983 | * cannot be allocated for the I/O request. | |
1984 | */ | |
1985 | int spdk_nvme_ns_cmd_compare_with_md(struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, | |
1986 | void *payload, void *metadata, | |
1987 | uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, | |
1988 | void *cb_arg, uint32_t io_flags, | |
1989 | uint16_t apptag_mask, uint16_t apptag); | |
1990 | ||
1991 | /** | |
1992 | * \brief Inject an error for the next request with a given opcode. | |
1993 | * | |
1994 | * \param ctrlr NVMe controller. | |
1995 | * \param qpair I/O queue pair to add the error command, | |
1996 | * NULL for Admin queue pair. | |
1997 | * \param opc Opcode for Admin or I/O commands. | |
1998 | * \param do_not_submit True if matching requests should not be submitted | |
1999 | * to the controller, but instead completed manually | |
2000 | * after timeout_in_us has expired. False if matching | |
2001 | * requests should be submitted to the controller and | |
2002 | * have their completion status modified after the | |
2003 | * controller completes the request. | |
2004 | * \param timeout_in_us Wait specified microseconds when do_not_submit is true. | |
2005 | * \param err_count Number of matching requests to inject errors. | |
2006 | * \param sct Status code type. | |
2007 | * \param sc Status code. | |
2008 | * | |
2009 | * \return 0 if successfully enabled, ENOMEM if an error command | |
2010 | * structure cannot be allocated. | |
2011 | * | |
2012 | * The function can be called multiple times to inject errors for different | |
2013 | * commands. If the opcode matches an existing entry, the existing entry | |
2014 | * will be updated with the values specified. | |
2015 | */ | |
2016 | int spdk_nvme_qpair_add_cmd_error_injection(struct spdk_nvme_ctrlr *ctrlr, | |
2017 | struct spdk_nvme_qpair *qpair, | |
2018 | uint8_t opc, | |
2019 | bool do_not_submit, | |
2020 | uint64_t timeout_in_us, | |
2021 | uint32_t err_count, | |
2022 | uint8_t sct, uint8_t sc); | |
2023 | ||
2024 | /** | |
2025 | * \brief Clear the specified NVMe command with error status. | |
2026 | * | |
2027 | * \param ctrlr NVMe controller. | |
2028 | * \param qpair I/O queue pair to remove the error command, | |
2029 | * \ NULL for Admin queue pair. | |
2030 | * \param opc Opcode for Admin or I/O commands. | |
2031 | * | |
2032 | * The function will remove specified command in the error list. | |
2033 | */ | |
2034 | void spdk_nvme_qpair_remove_cmd_error_injection(struct spdk_nvme_ctrlr *ctrlr, | |
2035 | struct spdk_nvme_qpair *qpair, | |
2036 | uint8_t opc); | |
2037 | ||
2038 | ||
7c673cae FG |
2039 | #ifdef __cplusplus |
2040 | } | |
2041 | #endif | |
2042 | ||
2043 | #endif |