]>
Commit | Line | Data |
---|---|---|
bdd6a90a FZ |
1 | /* |
2 | * NVMe block driver based on vfio | |
3 | * | |
4 | * Copyright 2016 - 2018 Red Hat, Inc. | |
5 | * | |
6 | * Authors: | |
7 | * Fam Zheng <famz@redhat.com> | |
8 | * Paolo Bonzini <pbonzini@redhat.com> | |
9 | * | |
10 | * This work is licensed under the terms of the GNU GPL, version 2 or later. | |
11 | * See the COPYING file in the top-level directory. | |
12 | */ | |
13 | ||
14 | #include "qemu/osdep.h" | |
15 | #include <linux/vfio.h> | |
16 | #include "qapi/error.h" | |
17 | #include "qapi/qmp/qdict.h" | |
18 | #include "qapi/qmp/qstring.h" | |
19 | #include "qemu/error-report.h" | |
db725815 | 20 | #include "qemu/main-loop.h" |
0b8fa32f | 21 | #include "qemu/module.h" |
bdd6a90a | 22 | #include "qemu/cutils.h" |
922a01a0 | 23 | #include "qemu/option.h" |
bdd6a90a FZ |
24 | #include "qemu/vfio-helpers.h" |
25 | #include "block/block_int.h" | |
e4ec5ad4 | 26 | #include "sysemu/replay.h" |
bdd6a90a FZ |
27 | #include "trace.h" |
28 | ||
a3d9a352 | 29 | #include "block/nvme.h" |
bdd6a90a FZ |
30 | |
31 | #define NVME_SQ_ENTRY_BYTES 64 | |
32 | #define NVME_CQ_ENTRY_BYTES 16 | |
33 | #define NVME_QUEUE_SIZE 128 | |
34 | #define NVME_BAR_SIZE 8192 | |
35 | ||
1086e95d SH |
36 | /* |
37 | * We have to leave one slot empty as that is the full queue case where | |
38 | * head == tail + 1. | |
39 | */ | |
40 | #define NVME_NUM_REQS (NVME_QUEUE_SIZE - 1) | |
41 | ||
b75fd5f5 SH |
42 | typedef struct BDRVNVMeState BDRVNVMeState; |
43 | ||
bdd6a90a FZ |
44 | typedef struct { |
45 | int32_t head, tail; | |
46 | uint8_t *queue; | |
47 | uint64_t iova; | |
48 | /* Hardware MMIO register */ | |
49 | volatile uint32_t *doorbell; | |
50 | } NVMeQueue; | |
51 | ||
52 | typedef struct { | |
53 | BlockCompletionFunc *cb; | |
54 | void *opaque; | |
55 | int cid; | |
56 | void *prp_list_page; | |
57 | uint64_t prp_list_iova; | |
1086e95d | 58 | int free_req_next; /* q->reqs[] index of next free req */ |
bdd6a90a FZ |
59 | } NVMeRequest; |
60 | ||
61 | typedef struct { | |
bdd6a90a FZ |
62 | QemuMutex lock; |
63 | ||
b75fd5f5 SH |
64 | /* Read from I/O code path, initialized under BQL */ |
65 | BDRVNVMeState *s; | |
66 | int index; | |
67 | ||
bdd6a90a | 68 | /* Fields protected by BQL */ |
bdd6a90a FZ |
69 | uint8_t *prp_list_pages; |
70 | ||
71 | /* Fields protected by @lock */ | |
a5db74f3 | 72 | CoQueue free_req_queue; |
bdd6a90a FZ |
73 | NVMeQueue sq, cq; |
74 | int cq_phase; | |
1086e95d SH |
75 | int free_req_head; |
76 | NVMeRequest reqs[NVME_NUM_REQS]; | |
bdd6a90a FZ |
77 | int need_kick; |
78 | int inflight; | |
7838c67f SH |
79 | |
80 | /* Thread-safe, no lock necessary */ | |
81 | QEMUBH *completion_bh; | |
bdd6a90a FZ |
82 | } NVMeQueuePair; |
83 | ||
84 | /* Memory mapped registers */ | |
85 | typedef volatile struct { | |
86 | uint64_t cap; | |
87 | uint32_t vs; | |
88 | uint32_t intms; | |
89 | uint32_t intmc; | |
90 | uint32_t cc; | |
91 | uint32_t reserved0; | |
92 | uint32_t csts; | |
93 | uint32_t nssr; | |
94 | uint32_t aqa; | |
95 | uint64_t asq; | |
96 | uint64_t acq; | |
97 | uint32_t cmbloc; | |
98 | uint32_t cmbsz; | |
99 | uint8_t reserved1[0xec0]; | |
100 | uint8_t cmd_set_specfic[0x100]; | |
101 | uint32_t doorbells[]; | |
83c68e14 | 102 | } NVMeRegs; |
bdd6a90a FZ |
103 | |
104 | QEMU_BUILD_BUG_ON(offsetof(NVMeRegs, doorbells) != 0x1000); | |
105 | ||
73159e52 PMD |
106 | #define INDEX_ADMIN 0 |
107 | #define INDEX_IO(n) (1 + n) | |
108 | ||
b75fd5f5 | 109 | struct BDRVNVMeState { |
bdd6a90a FZ |
110 | AioContext *aio_context; |
111 | QEMUVFIOState *vfio; | |
112 | NVMeRegs *regs; | |
113 | /* The submission/completion queue pairs. | |
114 | * [0]: admin queue. | |
115 | * [1..]: io queues. | |
116 | */ | |
117 | NVMeQueuePair **queues; | |
118 | int nr_queues; | |
119 | size_t page_size; | |
120 | /* How many uint32_t elements does each doorbell entry take. */ | |
121 | size_t doorbell_scale; | |
122 | bool write_cache_supported; | |
123 | EventNotifier irq_notifier; | |
118d1b6a | 124 | |
bdd6a90a FZ |
125 | uint64_t nsze; /* Namespace size reported by identify command */ |
126 | int nsid; /* The namespace id to read/write data. */ | |
1120407b | 127 | int blkshift; |
118d1b6a | 128 | |
bdd6a90a | 129 | uint64_t max_transfer; |
2f0d8947 | 130 | bool plugged; |
bdd6a90a | 131 | |
e0dd95e3 | 132 | bool supports_write_zeroes; |
e87a09d6 | 133 | bool supports_discard; |
e0dd95e3 | 134 | |
bdd6a90a FZ |
135 | CoMutex dma_map_lock; |
136 | CoQueue dma_flush_queue; | |
137 | ||
138 | /* Total size of mapped qiov, accessed under dma_map_lock */ | |
139 | int dma_map_count; | |
cc61b074 HR |
140 | |
141 | /* PCI address (required for nvme_refresh_filename()) */ | |
142 | char *device; | |
b75fd5f5 | 143 | }; |
bdd6a90a FZ |
144 | |
145 | #define NVME_BLOCK_OPT_DEVICE "device" | |
146 | #define NVME_BLOCK_OPT_NAMESPACE "namespace" | |
147 | ||
7838c67f SH |
148 | static void nvme_process_completion_bh(void *opaque); |
149 | ||
bdd6a90a FZ |
150 | static QemuOptsList runtime_opts = { |
151 | .name = "nvme", | |
152 | .head = QTAILQ_HEAD_INITIALIZER(runtime_opts.head), | |
153 | .desc = { | |
154 | { | |
155 | .name = NVME_BLOCK_OPT_DEVICE, | |
156 | .type = QEMU_OPT_STRING, | |
157 | .help = "NVMe PCI device address", | |
158 | }, | |
159 | { | |
160 | .name = NVME_BLOCK_OPT_NAMESPACE, | |
161 | .type = QEMU_OPT_NUMBER, | |
162 | .help = "NVMe namespace", | |
163 | }, | |
164 | { /* end of list */ } | |
165 | }, | |
166 | }; | |
167 | ||
168 | static void nvme_init_queue(BlockDriverState *bs, NVMeQueue *q, | |
169 | int nentries, int entry_bytes, Error **errp) | |
170 | { | |
171 | BDRVNVMeState *s = bs->opaque; | |
172 | size_t bytes; | |
173 | int r; | |
174 | ||
175 | bytes = ROUND_UP(nentries * entry_bytes, s->page_size); | |
176 | q->head = q->tail = 0; | |
177 | q->queue = qemu_try_blockalign0(bs, bytes); | |
178 | ||
179 | if (!q->queue) { | |
180 | error_setg(errp, "Cannot allocate queue"); | |
181 | return; | |
182 | } | |
183 | r = qemu_vfio_dma_map(s->vfio, q->queue, bytes, false, &q->iova); | |
184 | if (r) { | |
185 | error_setg(errp, "Cannot map queue"); | |
186 | } | |
187 | } | |
188 | ||
b75fd5f5 | 189 | static void nvme_free_queue_pair(NVMeQueuePair *q) |
bdd6a90a | 190 | { |
7838c67f SH |
191 | if (q->completion_bh) { |
192 | qemu_bh_delete(q->completion_bh); | |
193 | } | |
bdd6a90a FZ |
194 | qemu_vfree(q->prp_list_pages); |
195 | qemu_vfree(q->sq.queue); | |
196 | qemu_vfree(q->cq.queue); | |
197 | qemu_mutex_destroy(&q->lock); | |
198 | g_free(q); | |
199 | } | |
200 | ||
201 | static void nvme_free_req_queue_cb(void *opaque) | |
202 | { | |
203 | NVMeQueuePair *q = opaque; | |
204 | ||
205 | qemu_mutex_lock(&q->lock); | |
206 | while (qemu_co_enter_next(&q->free_req_queue, &q->lock)) { | |
207 | /* Retry all pending requests */ | |
208 | } | |
209 | qemu_mutex_unlock(&q->lock); | |
210 | } | |
211 | ||
212 | static NVMeQueuePair *nvme_create_queue_pair(BlockDriverState *bs, | |
213 | int idx, int size, | |
214 | Error **errp) | |
215 | { | |
216 | int i, r; | |
217 | BDRVNVMeState *s = bs->opaque; | |
218 | Error *local_err = NULL; | |
0ea45f76 | 219 | NVMeQueuePair *q; |
bdd6a90a FZ |
220 | uint64_t prp_list_iova; |
221 | ||
0ea45f76 PMD |
222 | q = g_try_new0(NVMeQueuePair, 1); |
223 | if (!q) { | |
224 | return NULL; | |
225 | } | |
226 | q->prp_list_pages = qemu_try_blockalign0(bs, | |
227 | s->page_size * NVME_NUM_REQS); | |
228 | if (!q->prp_list_pages) { | |
229 | goto fail; | |
230 | } | |
bdd6a90a | 231 | qemu_mutex_init(&q->lock); |
b75fd5f5 | 232 | q->s = s; |
bdd6a90a FZ |
233 | q->index = idx; |
234 | qemu_co_queue_init(&q->free_req_queue); | |
7838c67f SH |
235 | q->completion_bh = aio_bh_new(bdrv_get_aio_context(bs), |
236 | nvme_process_completion_bh, q); | |
bdd6a90a | 237 | r = qemu_vfio_dma_map(s->vfio, q->prp_list_pages, |
1086e95d | 238 | s->page_size * NVME_NUM_REQS, |
bdd6a90a FZ |
239 | false, &prp_list_iova); |
240 | if (r) { | |
241 | goto fail; | |
242 | } | |
1086e95d SH |
243 | q->free_req_head = -1; |
244 | for (i = 0; i < NVME_NUM_REQS; i++) { | |
bdd6a90a FZ |
245 | NVMeRequest *req = &q->reqs[i]; |
246 | req->cid = i + 1; | |
1086e95d SH |
247 | req->free_req_next = q->free_req_head; |
248 | q->free_req_head = i; | |
bdd6a90a FZ |
249 | req->prp_list_page = q->prp_list_pages + i * s->page_size; |
250 | req->prp_list_iova = prp_list_iova + i * s->page_size; | |
251 | } | |
1086e95d | 252 | |
bdd6a90a FZ |
253 | nvme_init_queue(bs, &q->sq, size, NVME_SQ_ENTRY_BYTES, &local_err); |
254 | if (local_err) { | |
255 | error_propagate(errp, local_err); | |
256 | goto fail; | |
257 | } | |
258 | q->sq.doorbell = &s->regs->doorbells[idx * 2 * s->doorbell_scale]; | |
259 | ||
260 | nvme_init_queue(bs, &q->cq, size, NVME_CQ_ENTRY_BYTES, &local_err); | |
261 | if (local_err) { | |
262 | error_propagate(errp, local_err); | |
263 | goto fail; | |
264 | } | |
461bba04 | 265 | q->cq.doorbell = &s->regs->doorbells[(idx * 2 + 1) * s->doorbell_scale]; |
bdd6a90a FZ |
266 | |
267 | return q; | |
268 | fail: | |
b75fd5f5 | 269 | nvme_free_queue_pair(q); |
bdd6a90a FZ |
270 | return NULL; |
271 | } | |
272 | ||
273 | /* With q->lock */ | |
b75fd5f5 | 274 | static void nvme_kick(NVMeQueuePair *q) |
bdd6a90a | 275 | { |
b75fd5f5 SH |
276 | BDRVNVMeState *s = q->s; |
277 | ||
bdd6a90a FZ |
278 | if (s->plugged || !q->need_kick) { |
279 | return; | |
280 | } | |
281 | trace_nvme_kick(s, q->index); | |
282 | assert(!(q->sq.tail & 0xFF00)); | |
283 | /* Fence the write to submission queue entry before notifying the device. */ | |
284 | smp_wmb(); | |
285 | *q->sq.doorbell = cpu_to_le32(q->sq.tail); | |
286 | q->inflight += q->need_kick; | |
287 | q->need_kick = 0; | |
288 | } | |
289 | ||
290 | /* Find a free request element if any, otherwise: | |
291 | * a) if in coroutine context, try to wait for one to become available; | |
292 | * b) if not in coroutine, return NULL; | |
293 | */ | |
294 | static NVMeRequest *nvme_get_free_req(NVMeQueuePair *q) | |
295 | { | |
1086e95d | 296 | NVMeRequest *req; |
bdd6a90a FZ |
297 | |
298 | qemu_mutex_lock(&q->lock); | |
1086e95d SH |
299 | |
300 | while (q->free_req_head == -1) { | |
bdd6a90a FZ |
301 | if (qemu_in_coroutine()) { |
302 | trace_nvme_free_req_queue_wait(q); | |
303 | qemu_co_queue_wait(&q->free_req_queue, &q->lock); | |
304 | } else { | |
305 | qemu_mutex_unlock(&q->lock); | |
306 | return NULL; | |
307 | } | |
308 | } | |
1086e95d SH |
309 | |
310 | req = &q->reqs[q->free_req_head]; | |
311 | q->free_req_head = req->free_req_next; | |
312 | req->free_req_next = -1; | |
313 | ||
bdd6a90a FZ |
314 | qemu_mutex_unlock(&q->lock); |
315 | return req; | |
316 | } | |
317 | ||
1086e95d SH |
318 | /* With q->lock */ |
319 | static void nvme_put_free_req_locked(NVMeQueuePair *q, NVMeRequest *req) | |
320 | { | |
321 | req->free_req_next = q->free_req_head; | |
322 | q->free_req_head = req - q->reqs; | |
323 | } | |
324 | ||
325 | /* With q->lock */ | |
b75fd5f5 | 326 | static void nvme_wake_free_req_locked(NVMeQueuePair *q) |
1086e95d SH |
327 | { |
328 | if (!qemu_co_queue_empty(&q->free_req_queue)) { | |
b75fd5f5 | 329 | replay_bh_schedule_oneshot_event(q->s->aio_context, |
1086e95d SH |
330 | nvme_free_req_queue_cb, q); |
331 | } | |
332 | } | |
333 | ||
334 | /* Insert a request in the freelist and wake waiters */ | |
b75fd5f5 | 335 | static void nvme_put_free_req_and_wake(NVMeQueuePair *q, NVMeRequest *req) |
1086e95d SH |
336 | { |
337 | qemu_mutex_lock(&q->lock); | |
338 | nvme_put_free_req_locked(q, req); | |
b75fd5f5 | 339 | nvme_wake_free_req_locked(q); |
1086e95d SH |
340 | qemu_mutex_unlock(&q->lock); |
341 | } | |
342 | ||
bdd6a90a FZ |
343 | static inline int nvme_translate_error(const NvmeCqe *c) |
344 | { | |
345 | uint16_t status = (le16_to_cpu(c->status) >> 1) & 0xFF; | |
346 | if (status) { | |
347 | trace_nvme_error(le32_to_cpu(c->result), | |
348 | le16_to_cpu(c->sq_head), | |
349 | le16_to_cpu(c->sq_id), | |
350 | le16_to_cpu(c->cid), | |
351 | le16_to_cpu(status)); | |
352 | } | |
353 | switch (status) { | |
354 | case 0: | |
355 | return 0; | |
356 | case 1: | |
357 | return -ENOSYS; | |
358 | case 2: | |
359 | return -EINVAL; | |
360 | default: | |
361 | return -EIO; | |
362 | } | |
363 | } | |
364 | ||
365 | /* With q->lock */ | |
b75fd5f5 | 366 | static bool nvme_process_completion(NVMeQueuePair *q) |
bdd6a90a | 367 | { |
b75fd5f5 | 368 | BDRVNVMeState *s = q->s; |
bdd6a90a FZ |
369 | bool progress = false; |
370 | NVMeRequest *preq; | |
371 | NVMeRequest req; | |
372 | NvmeCqe *c; | |
373 | ||
374 | trace_nvme_process_completion(s, q->index, q->inflight); | |
7838c67f SH |
375 | if (s->plugged) { |
376 | trace_nvme_process_completion_queue_plugged(s, q->index); | |
bdd6a90a FZ |
377 | return false; |
378 | } | |
7838c67f SH |
379 | |
380 | /* | |
381 | * Support re-entrancy when a request cb() function invokes aio_poll(). | |
382 | * Pending completions must be visible to aio_poll() so that a cb() | |
383 | * function can wait for the completion of another request. | |
384 | * | |
385 | * The aio_poll() loop will execute our BH and we'll resume completion | |
386 | * processing there. | |
387 | */ | |
388 | qemu_bh_schedule(q->completion_bh); | |
389 | ||
bdd6a90a FZ |
390 | assert(q->inflight >= 0); |
391 | while (q->inflight) { | |
04b3fb39 | 392 | int ret; |
bdd6a90a | 393 | int16_t cid; |
04b3fb39 | 394 | |
bdd6a90a | 395 | c = (NvmeCqe *)&q->cq.queue[q->cq.head * NVME_CQ_ENTRY_BYTES]; |
258867d1 | 396 | if ((le16_to_cpu(c->status) & 0x1) == q->cq_phase) { |
bdd6a90a FZ |
397 | break; |
398 | } | |
04b3fb39 | 399 | ret = nvme_translate_error(c); |
bdd6a90a FZ |
400 | q->cq.head = (q->cq.head + 1) % NVME_QUEUE_SIZE; |
401 | if (!q->cq.head) { | |
402 | q->cq_phase = !q->cq_phase; | |
403 | } | |
404 | cid = le16_to_cpu(c->cid); | |
405 | if (cid == 0 || cid > NVME_QUEUE_SIZE) { | |
406 | fprintf(stderr, "Unexpected CID in completion queue: %" PRIu32 "\n", | |
407 | cid); | |
408 | continue; | |
409 | } | |
bdd6a90a FZ |
410 | trace_nvme_complete_command(s, q->index, cid); |
411 | preq = &q->reqs[cid - 1]; | |
412 | req = *preq; | |
413 | assert(req.cid == cid); | |
414 | assert(req.cb); | |
1086e95d | 415 | nvme_put_free_req_locked(q, preq); |
bdd6a90a | 416 | preq->cb = preq->opaque = NULL; |
7838c67f | 417 | q->inflight--; |
bdd6a90a | 418 | qemu_mutex_unlock(&q->lock); |
04b3fb39 | 419 | req.cb(req.opaque, ret); |
bdd6a90a | 420 | qemu_mutex_lock(&q->lock); |
bdd6a90a FZ |
421 | progress = true; |
422 | } | |
423 | if (progress) { | |
424 | /* Notify the device so it can post more completions. */ | |
425 | smp_mb_release(); | |
426 | *q->cq.doorbell = cpu_to_le32(q->cq.head); | |
b75fd5f5 | 427 | nvme_wake_free_req_locked(q); |
bdd6a90a | 428 | } |
7838c67f SH |
429 | |
430 | qemu_bh_cancel(q->completion_bh); | |
431 | ||
bdd6a90a FZ |
432 | return progress; |
433 | } | |
434 | ||
7838c67f SH |
435 | static void nvme_process_completion_bh(void *opaque) |
436 | { | |
437 | NVMeQueuePair *q = opaque; | |
438 | ||
439 | /* | |
440 | * We're being invoked because a nvme_process_completion() cb() function | |
441 | * called aio_poll(). The callback may be waiting for further completions | |
442 | * so notify the device that it has space to fill in more completions now. | |
443 | */ | |
444 | smp_mb_release(); | |
445 | *q->cq.doorbell = cpu_to_le32(q->cq.head); | |
446 | nvme_wake_free_req_locked(q); | |
447 | ||
448 | nvme_process_completion(q); | |
449 | } | |
450 | ||
bdd6a90a FZ |
451 | static void nvme_trace_command(const NvmeCmd *cmd) |
452 | { | |
453 | int i; | |
454 | ||
e266f52c PMD |
455 | if (!trace_event_get_state_backends(TRACE_NVME_SUBMIT_COMMAND_RAW)) { |
456 | return; | |
457 | } | |
bdd6a90a FZ |
458 | for (i = 0; i < 8; ++i) { |
459 | uint8_t *cmdp = (uint8_t *)cmd + i * 8; | |
460 | trace_nvme_submit_command_raw(cmdp[0], cmdp[1], cmdp[2], cmdp[3], | |
461 | cmdp[4], cmdp[5], cmdp[6], cmdp[7]); | |
462 | } | |
463 | } | |
464 | ||
b75fd5f5 | 465 | static void nvme_submit_command(NVMeQueuePair *q, NVMeRequest *req, |
bdd6a90a FZ |
466 | NvmeCmd *cmd, BlockCompletionFunc cb, |
467 | void *opaque) | |
468 | { | |
469 | assert(!req->cb); | |
470 | req->cb = cb; | |
471 | req->opaque = opaque; | |
472 | cmd->cid = cpu_to_le32(req->cid); | |
473 | ||
b75fd5f5 | 474 | trace_nvme_submit_command(q->s, q->index, req->cid); |
bdd6a90a FZ |
475 | nvme_trace_command(cmd); |
476 | qemu_mutex_lock(&q->lock); | |
477 | memcpy((uint8_t *)q->sq.queue + | |
478 | q->sq.tail * NVME_SQ_ENTRY_BYTES, cmd, sizeof(*cmd)); | |
479 | q->sq.tail = (q->sq.tail + 1) % NVME_QUEUE_SIZE; | |
480 | q->need_kick++; | |
b75fd5f5 SH |
481 | nvme_kick(q); |
482 | nvme_process_completion(q); | |
bdd6a90a FZ |
483 | qemu_mutex_unlock(&q->lock); |
484 | } | |
485 | ||
486 | static void nvme_cmd_sync_cb(void *opaque, int ret) | |
487 | { | |
488 | int *pret = opaque; | |
489 | *pret = ret; | |
4720cbee | 490 | aio_wait_kick(); |
bdd6a90a FZ |
491 | } |
492 | ||
493 | static int nvme_cmd_sync(BlockDriverState *bs, NVMeQueuePair *q, | |
494 | NvmeCmd *cmd) | |
495 | { | |
496 | NVMeRequest *req; | |
bdd6a90a FZ |
497 | int ret = -EINPROGRESS; |
498 | req = nvme_get_free_req(q); | |
499 | if (!req) { | |
500 | return -EBUSY; | |
501 | } | |
b75fd5f5 | 502 | nvme_submit_command(q, req, cmd, nvme_cmd_sync_cb, &ret); |
bdd6a90a FZ |
503 | |
504 | BDRV_POLL_WHILE(bs, ret == -EINPROGRESS); | |
505 | return ret; | |
506 | } | |
507 | ||
508 | static void nvme_identify(BlockDriverState *bs, int namespace, Error **errp) | |
509 | { | |
510 | BDRVNVMeState *s = bs->opaque; | |
7d3b214a PMD |
511 | union { |
512 | NvmeIdCtrl ctrl; | |
513 | NvmeIdNs ns; | |
514 | } *id; | |
118d1b6a | 515 | NvmeLBAF *lbaf; |
e0dd95e3 | 516 | uint16_t oncs; |
1120407b | 517 | int r; |
bdd6a90a FZ |
518 | uint64_t iova; |
519 | NvmeCmd cmd = { | |
520 | .opcode = NVME_ADM_CMD_IDENTIFY, | |
521 | .cdw10 = cpu_to_le32(0x1), | |
522 | }; | |
523 | ||
7d3b214a | 524 | id = qemu_try_blockalign0(bs, sizeof(*id)); |
4d980939 | 525 | if (!id) { |
bdd6a90a FZ |
526 | error_setg(errp, "Cannot allocate buffer for identify response"); |
527 | goto out; | |
528 | } | |
7d3b214a | 529 | r = qemu_vfio_dma_map(s->vfio, id, sizeof(*id), true, &iova); |
bdd6a90a FZ |
530 | if (r) { |
531 | error_setg(errp, "Cannot map buffer for DMA"); | |
532 | goto out; | |
533 | } | |
c26f2173 | 534 | cmd.dptr.prp1 = cpu_to_le64(iova); |
bdd6a90a | 535 | |
73159e52 | 536 | if (nvme_cmd_sync(bs, s->queues[INDEX_ADMIN], &cmd)) { |
bdd6a90a FZ |
537 | error_setg(errp, "Failed to identify controller"); |
538 | goto out; | |
539 | } | |
540 | ||
7d3b214a | 541 | if (le32_to_cpu(id->ctrl.nn) < namespace) { |
bdd6a90a FZ |
542 | error_setg(errp, "Invalid namespace"); |
543 | goto out; | |
544 | } | |
7d3b214a PMD |
545 | s->write_cache_supported = le32_to_cpu(id->ctrl.vwc) & 0x1; |
546 | s->max_transfer = (id->ctrl.mdts ? 1 << id->ctrl.mdts : 0) * s->page_size; | |
bdd6a90a FZ |
547 | /* For now the page list buffer per command is one page, to hold at most |
548 | * s->page_size / sizeof(uint64_t) entries. */ | |
549 | s->max_transfer = MIN_NON_ZERO(s->max_transfer, | |
550 | s->page_size / sizeof(uint64_t) * s->page_size); | |
551 | ||
7d3b214a | 552 | oncs = le16_to_cpu(id->ctrl.oncs); |
69265150 | 553 | s->supports_write_zeroes = !!(oncs & NVME_ONCS_WRITE_ZEROES); |
e87a09d6 | 554 | s->supports_discard = !!(oncs & NVME_ONCS_DSM); |
e0dd95e3 | 555 | |
7d3b214a | 556 | memset(id, 0, sizeof(*id)); |
bdd6a90a FZ |
557 | cmd.cdw10 = 0; |
558 | cmd.nsid = cpu_to_le32(namespace); | |
73159e52 | 559 | if (nvme_cmd_sync(bs, s->queues[INDEX_ADMIN], &cmd)) { |
bdd6a90a FZ |
560 | error_setg(errp, "Failed to identify namespace"); |
561 | goto out; | |
562 | } | |
563 | ||
7d3b214a PMD |
564 | s->nsze = le64_to_cpu(id->ns.nsze); |
565 | lbaf = &id->ns.lbaf[NVME_ID_NS_FLBAS_INDEX(id->ns.flbas)]; | |
118d1b6a | 566 | |
7d3b214a PMD |
567 | if (NVME_ID_NS_DLFEAT_WRITE_ZEROES(id->ns.dlfeat) && |
568 | NVME_ID_NS_DLFEAT_READ_BEHAVIOR(id->ns.dlfeat) == | |
e0dd95e3 ML |
569 | NVME_ID_NS_DLFEAT_READ_BEHAVIOR_ZEROES) { |
570 | bs->supported_write_flags |= BDRV_REQ_MAY_UNMAP; | |
571 | } | |
572 | ||
118d1b6a ML |
573 | if (lbaf->ms) { |
574 | error_setg(errp, "Namespaces with metadata are not yet supported"); | |
575 | goto out; | |
576 | } | |
577 | ||
1120407b HR |
578 | if (lbaf->ds < BDRV_SECTOR_BITS || lbaf->ds > 12 || |
579 | (1 << lbaf->ds) > s->page_size) | |
580 | { | |
581 | error_setg(errp, "Namespace has unsupported block size (2^%d)", | |
582 | lbaf->ds); | |
118d1b6a ML |
583 | goto out; |
584 | } | |
bdd6a90a | 585 | |
118d1b6a | 586 | s->blkshift = lbaf->ds; |
bdd6a90a | 587 | out: |
4d980939 PMD |
588 | qemu_vfio_dma_unmap(s->vfio, id); |
589 | qemu_vfree(id); | |
bdd6a90a FZ |
590 | } |
591 | ||
592 | static bool nvme_poll_queues(BDRVNVMeState *s) | |
593 | { | |
594 | bool progress = false; | |
595 | int i; | |
596 | ||
597 | for (i = 0; i < s->nr_queues; i++) { | |
598 | NVMeQueuePair *q = s->queues[i]; | |
2446e0e2 SH |
599 | const size_t cqe_offset = q->cq.head * NVME_CQ_ENTRY_BYTES; |
600 | NvmeCqe *cqe = (NvmeCqe *)&q->cq.queue[cqe_offset]; | |
601 | ||
602 | /* | |
603 | * Do an early check for completions. q->lock isn't needed because | |
604 | * nvme_process_completion() only runs in the event loop thread and | |
605 | * cannot race with itself. | |
606 | */ | |
607 | if ((le16_to_cpu(cqe->status) & 0x1) == q->cq_phase) { | |
608 | continue; | |
609 | } | |
610 | ||
bdd6a90a | 611 | qemu_mutex_lock(&q->lock); |
b75fd5f5 | 612 | while (nvme_process_completion(q)) { |
bdd6a90a FZ |
613 | /* Keep polling */ |
614 | progress = true; | |
615 | } | |
616 | qemu_mutex_unlock(&q->lock); | |
617 | } | |
618 | return progress; | |
619 | } | |
620 | ||
621 | static void nvme_handle_event(EventNotifier *n) | |
622 | { | |
623 | BDRVNVMeState *s = container_of(n, BDRVNVMeState, irq_notifier); | |
624 | ||
625 | trace_nvme_handle_event(s); | |
bdd6a90a FZ |
626 | event_notifier_test_and_clear(n); |
627 | nvme_poll_queues(s); | |
bdd6a90a FZ |
628 | } |
629 | ||
630 | static bool nvme_add_io_queue(BlockDriverState *bs, Error **errp) | |
631 | { | |
632 | BDRVNVMeState *s = bs->opaque; | |
633 | int n = s->nr_queues; | |
634 | NVMeQueuePair *q; | |
635 | NvmeCmd cmd; | |
636 | int queue_size = NVME_QUEUE_SIZE; | |
637 | ||
638 | q = nvme_create_queue_pair(bs, n, queue_size, errp); | |
639 | if (!q) { | |
640 | return false; | |
641 | } | |
642 | cmd = (NvmeCmd) { | |
643 | .opcode = NVME_ADM_CMD_CREATE_CQ, | |
c26f2173 | 644 | .dptr.prp1 = cpu_to_le64(q->cq.iova), |
bdd6a90a FZ |
645 | .cdw10 = cpu_to_le32(((queue_size - 1) << 16) | (n & 0xFFFF)), |
646 | .cdw11 = cpu_to_le32(0x3), | |
647 | }; | |
73159e52 | 648 | if (nvme_cmd_sync(bs, s->queues[INDEX_ADMIN], &cmd)) { |
bf6ce5ec | 649 | error_setg(errp, "Failed to create CQ io queue [%d]", n); |
c8edbfb2 | 650 | goto out_error; |
bdd6a90a FZ |
651 | } |
652 | cmd = (NvmeCmd) { | |
653 | .opcode = NVME_ADM_CMD_CREATE_SQ, | |
c26f2173 | 654 | .dptr.prp1 = cpu_to_le64(q->sq.iova), |
bdd6a90a FZ |
655 | .cdw10 = cpu_to_le32(((queue_size - 1) << 16) | (n & 0xFFFF)), |
656 | .cdw11 = cpu_to_le32(0x1 | (n << 16)), | |
657 | }; | |
73159e52 | 658 | if (nvme_cmd_sync(bs, s->queues[INDEX_ADMIN], &cmd)) { |
bf6ce5ec | 659 | error_setg(errp, "Failed to create SQ io queue [%d]", n); |
c8edbfb2 | 660 | goto out_error; |
bdd6a90a FZ |
661 | } |
662 | s->queues = g_renew(NVMeQueuePair *, s->queues, n + 1); | |
663 | s->queues[n] = q; | |
664 | s->nr_queues++; | |
665 | return true; | |
c8edbfb2 PMD |
666 | out_error: |
667 | nvme_free_queue_pair(q); | |
668 | return false; | |
bdd6a90a FZ |
669 | } |
670 | ||
671 | static bool nvme_poll_cb(void *opaque) | |
672 | { | |
673 | EventNotifier *e = opaque; | |
674 | BDRVNVMeState *s = container_of(e, BDRVNVMeState, irq_notifier); | |
bdd6a90a FZ |
675 | |
676 | trace_nvme_poll_cb(s); | |
b3ac2b94 | 677 | return nvme_poll_queues(s); |
bdd6a90a FZ |
678 | } |
679 | ||
680 | static int nvme_init(BlockDriverState *bs, const char *device, int namespace, | |
681 | Error **errp) | |
682 | { | |
683 | BDRVNVMeState *s = bs->opaque; | |
684 | int ret; | |
685 | uint64_t cap; | |
686 | uint64_t timeout_ms; | |
687 | uint64_t deadline, now; | |
688 | Error *local_err = NULL; | |
689 | ||
690 | qemu_co_mutex_init(&s->dma_map_lock); | |
691 | qemu_co_queue_init(&s->dma_flush_queue); | |
cc61b074 | 692 | s->device = g_strdup(device); |
bdd6a90a FZ |
693 | s->nsid = namespace; |
694 | s->aio_context = bdrv_get_aio_context(bs); | |
695 | ret = event_notifier_init(&s->irq_notifier, 0); | |
696 | if (ret) { | |
697 | error_setg(errp, "Failed to init event notifier"); | |
698 | return ret; | |
699 | } | |
700 | ||
701 | s->vfio = qemu_vfio_open_pci(device, errp); | |
702 | if (!s->vfio) { | |
703 | ret = -EINVAL; | |
9582f357 | 704 | goto out; |
bdd6a90a FZ |
705 | } |
706 | ||
707 | s->regs = qemu_vfio_pci_map_bar(s->vfio, 0, 0, NVME_BAR_SIZE, errp); | |
708 | if (!s->regs) { | |
709 | ret = -EINVAL; | |
9582f357 | 710 | goto out; |
bdd6a90a FZ |
711 | } |
712 | ||
713 | /* Perform initialize sequence as described in NVMe spec "7.6.1 | |
714 | * Initialization". */ | |
715 | ||
716 | cap = le64_to_cpu(s->regs->cap); | |
717 | if (!(cap & (1ULL << 37))) { | |
718 | error_setg(errp, "Device doesn't support NVMe command set"); | |
719 | ret = -EINVAL; | |
9582f357 | 720 | goto out; |
bdd6a90a FZ |
721 | } |
722 | ||
723 | s->page_size = MAX(4096, 1 << (12 + ((cap >> 48) & 0xF))); | |
724 | s->doorbell_scale = (4 << (((cap >> 32) & 0xF))) / sizeof(uint32_t); | |
725 | bs->bl.opt_mem_alignment = s->page_size; | |
726 | timeout_ms = MIN(500 * ((cap >> 24) & 0xFF), 30000); | |
727 | ||
728 | /* Reset device to get a clean state. */ | |
729 | s->regs->cc = cpu_to_le32(le32_to_cpu(s->regs->cc) & 0xFE); | |
730 | /* Wait for CSTS.RDY = 0. */ | |
e4f310fe | 731 | deadline = qemu_clock_get_ns(QEMU_CLOCK_REALTIME) + timeout_ms * SCALE_MS; |
bdd6a90a FZ |
732 | while (le32_to_cpu(s->regs->csts) & 0x1) { |
733 | if (qemu_clock_get_ns(QEMU_CLOCK_REALTIME) > deadline) { | |
734 | error_setg(errp, "Timeout while waiting for device to reset (%" | |
735 | PRId64 " ms)", | |
736 | timeout_ms); | |
737 | ret = -ETIMEDOUT; | |
9582f357 | 738 | goto out; |
bdd6a90a FZ |
739 | } |
740 | } | |
741 | ||
742 | /* Set up admin queue. */ | |
743 | s->queues = g_new(NVMeQueuePair *, 1); | |
73159e52 PMD |
744 | s->queues[INDEX_ADMIN] = nvme_create_queue_pair(bs, 0, |
745 | NVME_QUEUE_SIZE, | |
746 | errp); | |
747 | if (!s->queues[INDEX_ADMIN]) { | |
bdd6a90a | 748 | ret = -EINVAL; |
9582f357 | 749 | goto out; |
bdd6a90a | 750 | } |
95667c3b | 751 | s->nr_queues = 1; |
bdd6a90a FZ |
752 | QEMU_BUILD_BUG_ON(NVME_QUEUE_SIZE & 0xF000); |
753 | s->regs->aqa = cpu_to_le32((NVME_QUEUE_SIZE << 16) | NVME_QUEUE_SIZE); | |
73159e52 PMD |
754 | s->regs->asq = cpu_to_le64(s->queues[INDEX_ADMIN]->sq.iova); |
755 | s->regs->acq = cpu_to_le64(s->queues[INDEX_ADMIN]->cq.iova); | |
bdd6a90a FZ |
756 | |
757 | /* After setting up all control registers we can enable device now. */ | |
758 | s->regs->cc = cpu_to_le32((ctz32(NVME_CQ_ENTRY_BYTES) << 20) | | |
759 | (ctz32(NVME_SQ_ENTRY_BYTES) << 16) | | |
760 | 0x1); | |
761 | /* Wait for CSTS.RDY = 1. */ | |
762 | now = qemu_clock_get_ns(QEMU_CLOCK_REALTIME); | |
763 | deadline = now + timeout_ms * 1000000; | |
764 | while (!(le32_to_cpu(s->regs->csts) & 0x1)) { | |
765 | if (qemu_clock_get_ns(QEMU_CLOCK_REALTIME) > deadline) { | |
766 | error_setg(errp, "Timeout while waiting for device to start (%" | |
767 | PRId64 " ms)", | |
768 | timeout_ms); | |
769 | ret = -ETIMEDOUT; | |
9582f357 | 770 | goto out; |
bdd6a90a FZ |
771 | } |
772 | } | |
773 | ||
774 | ret = qemu_vfio_pci_init_irq(s->vfio, &s->irq_notifier, | |
775 | VFIO_PCI_MSIX_IRQ_INDEX, errp); | |
776 | if (ret) { | |
9582f357 | 777 | goto out; |
bdd6a90a FZ |
778 | } |
779 | aio_set_event_notifier(bdrv_get_aio_context(bs), &s->irq_notifier, | |
780 | false, nvme_handle_event, nvme_poll_cb); | |
781 | ||
78d8c99e | 782 | nvme_identify(bs, namespace, &local_err); |
bdd6a90a FZ |
783 | if (local_err) { |
784 | error_propagate(errp, local_err); | |
785 | ret = -EIO; | |
9582f357 | 786 | goto out; |
bdd6a90a FZ |
787 | } |
788 | ||
789 | /* Set up command queues. */ | |
790 | if (!nvme_add_io_queue(bs, errp)) { | |
791 | ret = -EIO; | |
bdd6a90a | 792 | } |
9582f357 FZ |
793 | out: |
794 | /* Cleaning up is done in nvme_file_open() upon error. */ | |
bdd6a90a FZ |
795 | return ret; |
796 | } | |
797 | ||
798 | /* Parse a filename in the format of nvme://XXXX:XX:XX.X/X. Example: | |
799 | * | |
800 | * nvme://0000:44:00.0/1 | |
801 | * | |
802 | * where the "nvme://" is a fixed form of the protocol prefix, the middle part | |
803 | * is the PCI address, and the last part is the namespace number starting from | |
804 | * 1 according to the NVMe spec. */ | |
805 | static void nvme_parse_filename(const char *filename, QDict *options, | |
806 | Error **errp) | |
807 | { | |
808 | int pref = strlen("nvme://"); | |
809 | ||
810 | if (strlen(filename) > pref && !strncmp(filename, "nvme://", pref)) { | |
811 | const char *tmp = filename + pref; | |
812 | char *device; | |
813 | const char *namespace; | |
814 | unsigned long ns; | |
815 | const char *slash = strchr(tmp, '/'); | |
816 | if (!slash) { | |
625eaca9 | 817 | qdict_put_str(options, NVME_BLOCK_OPT_DEVICE, tmp); |
bdd6a90a FZ |
818 | return; |
819 | } | |
820 | device = g_strndup(tmp, slash - tmp); | |
625eaca9 | 821 | qdict_put_str(options, NVME_BLOCK_OPT_DEVICE, device); |
bdd6a90a FZ |
822 | g_free(device); |
823 | namespace = slash + 1; | |
824 | if (*namespace && qemu_strtoul(namespace, NULL, 10, &ns)) { | |
825 | error_setg(errp, "Invalid namespace '%s', positive number expected", | |
826 | namespace); | |
827 | return; | |
828 | } | |
625eaca9 LV |
829 | qdict_put_str(options, NVME_BLOCK_OPT_NAMESPACE, |
830 | *namespace ? namespace : "1"); | |
bdd6a90a FZ |
831 | } |
832 | } | |
833 | ||
834 | static int nvme_enable_disable_write_cache(BlockDriverState *bs, bool enable, | |
835 | Error **errp) | |
836 | { | |
837 | int ret; | |
838 | BDRVNVMeState *s = bs->opaque; | |
839 | NvmeCmd cmd = { | |
840 | .opcode = NVME_ADM_CMD_SET_FEATURES, | |
841 | .nsid = cpu_to_le32(s->nsid), | |
842 | .cdw10 = cpu_to_le32(0x06), | |
843 | .cdw11 = cpu_to_le32(enable ? 0x01 : 0x00), | |
844 | }; | |
845 | ||
73159e52 | 846 | ret = nvme_cmd_sync(bs, s->queues[INDEX_ADMIN], &cmd); |
bdd6a90a FZ |
847 | if (ret) { |
848 | error_setg(errp, "Failed to configure NVMe write cache"); | |
849 | } | |
850 | return ret; | |
851 | } | |
852 | ||
853 | static void nvme_close(BlockDriverState *bs) | |
854 | { | |
855 | int i; | |
856 | BDRVNVMeState *s = bs->opaque; | |
857 | ||
858 | for (i = 0; i < s->nr_queues; ++i) { | |
b75fd5f5 | 859 | nvme_free_queue_pair(s->queues[i]); |
bdd6a90a | 860 | } |
9582f357 | 861 | g_free(s->queues); |
bdd6a90a FZ |
862 | aio_set_event_notifier(bdrv_get_aio_context(bs), &s->irq_notifier, |
863 | false, NULL, NULL); | |
9582f357 | 864 | event_notifier_cleanup(&s->irq_notifier); |
bdd6a90a FZ |
865 | qemu_vfio_pci_unmap_bar(s->vfio, 0, (void *)s->regs, 0, NVME_BAR_SIZE); |
866 | qemu_vfio_close(s->vfio); | |
cc61b074 HR |
867 | |
868 | g_free(s->device); | |
bdd6a90a FZ |
869 | } |
870 | ||
871 | static int nvme_file_open(BlockDriverState *bs, QDict *options, int flags, | |
872 | Error **errp) | |
873 | { | |
874 | const char *device; | |
875 | QemuOpts *opts; | |
876 | int namespace; | |
877 | int ret; | |
878 | BDRVNVMeState *s = bs->opaque; | |
879 | ||
e0dd95e3 ML |
880 | bs->supported_write_flags = BDRV_REQ_FUA; |
881 | ||
bdd6a90a FZ |
882 | opts = qemu_opts_create(&runtime_opts, NULL, 0, &error_abort); |
883 | qemu_opts_absorb_qdict(opts, options, &error_abort); | |
884 | device = qemu_opt_get(opts, NVME_BLOCK_OPT_DEVICE); | |
885 | if (!device) { | |
886 | error_setg(errp, "'" NVME_BLOCK_OPT_DEVICE "' option is required"); | |
887 | qemu_opts_del(opts); | |
888 | return -EINVAL; | |
889 | } | |
890 | ||
891 | namespace = qemu_opt_get_number(opts, NVME_BLOCK_OPT_NAMESPACE, 1); | |
892 | ret = nvme_init(bs, device, namespace, errp); | |
893 | qemu_opts_del(opts); | |
894 | if (ret) { | |
895 | goto fail; | |
896 | } | |
897 | if (flags & BDRV_O_NOCACHE) { | |
898 | if (!s->write_cache_supported) { | |
899 | error_setg(errp, | |
900 | "NVMe controller doesn't support write cache configuration"); | |
901 | ret = -EINVAL; | |
902 | } else { | |
903 | ret = nvme_enable_disable_write_cache(bs, !(flags & BDRV_O_NOCACHE), | |
904 | errp); | |
905 | } | |
906 | if (ret) { | |
907 | goto fail; | |
908 | } | |
909 | } | |
bdd6a90a FZ |
910 | return 0; |
911 | fail: | |
912 | nvme_close(bs); | |
913 | return ret; | |
914 | } | |
915 | ||
916 | static int64_t nvme_getlength(BlockDriverState *bs) | |
917 | { | |
918 | BDRVNVMeState *s = bs->opaque; | |
118d1b6a ML |
919 | return s->nsze << s->blkshift; |
920 | } | |
bdd6a90a | 921 | |
1120407b | 922 | static uint32_t nvme_get_blocksize(BlockDriverState *bs) |
118d1b6a ML |
923 | { |
924 | BDRVNVMeState *s = bs->opaque; | |
1120407b HR |
925 | assert(s->blkshift >= BDRV_SECTOR_BITS && s->blkshift <= 12); |
926 | return UINT32_C(1) << s->blkshift; | |
118d1b6a ML |
927 | } |
928 | ||
929 | static int nvme_probe_blocksizes(BlockDriverState *bs, BlockSizes *bsz) | |
930 | { | |
1120407b | 931 | uint32_t blocksize = nvme_get_blocksize(bs); |
118d1b6a ML |
932 | bsz->phys = blocksize; |
933 | bsz->log = blocksize; | |
934 | return 0; | |
bdd6a90a FZ |
935 | } |
936 | ||
937 | /* Called with s->dma_map_lock */ | |
938 | static coroutine_fn int nvme_cmd_unmap_qiov(BlockDriverState *bs, | |
939 | QEMUIOVector *qiov) | |
940 | { | |
941 | int r = 0; | |
942 | BDRVNVMeState *s = bs->opaque; | |
943 | ||
944 | s->dma_map_count -= qiov->size; | |
945 | if (!s->dma_map_count && !qemu_co_queue_empty(&s->dma_flush_queue)) { | |
946 | r = qemu_vfio_dma_reset_temporary(s->vfio); | |
947 | if (!r) { | |
948 | qemu_co_queue_restart_all(&s->dma_flush_queue); | |
949 | } | |
950 | } | |
951 | return r; | |
952 | } | |
953 | ||
954 | /* Called with s->dma_map_lock */ | |
955 | static coroutine_fn int nvme_cmd_map_qiov(BlockDriverState *bs, NvmeCmd *cmd, | |
956 | NVMeRequest *req, QEMUIOVector *qiov) | |
957 | { | |
958 | BDRVNVMeState *s = bs->opaque; | |
959 | uint64_t *pagelist = req->prp_list_page; | |
960 | int i, j, r; | |
961 | int entries = 0; | |
962 | ||
963 | assert(qiov->size); | |
964 | assert(QEMU_IS_ALIGNED(qiov->size, s->page_size)); | |
965 | assert(qiov->size / s->page_size <= s->page_size / sizeof(uint64_t)); | |
966 | for (i = 0; i < qiov->niov; ++i) { | |
967 | bool retry = true; | |
968 | uint64_t iova; | |
969 | try_map: | |
970 | r = qemu_vfio_dma_map(s->vfio, | |
971 | qiov->iov[i].iov_base, | |
972 | qiov->iov[i].iov_len, | |
973 | true, &iova); | |
974 | if (r == -ENOMEM && retry) { | |
975 | retry = false; | |
976 | trace_nvme_dma_flush_queue_wait(s); | |
977 | if (s->dma_map_count) { | |
978 | trace_nvme_dma_map_flush(s); | |
979 | qemu_co_queue_wait(&s->dma_flush_queue, &s->dma_map_lock); | |
980 | } else { | |
981 | r = qemu_vfio_dma_reset_temporary(s->vfio); | |
982 | if (r) { | |
983 | goto fail; | |
984 | } | |
985 | } | |
986 | goto try_map; | |
987 | } | |
988 | if (r) { | |
989 | goto fail; | |
990 | } | |
991 | ||
992 | for (j = 0; j < qiov->iov[i].iov_len / s->page_size; j++) { | |
2916405a | 993 | pagelist[entries++] = cpu_to_le64(iova + j * s->page_size); |
bdd6a90a FZ |
994 | } |
995 | trace_nvme_cmd_map_qiov_iov(s, i, qiov->iov[i].iov_base, | |
996 | qiov->iov[i].iov_len / s->page_size); | |
997 | } | |
998 | ||
999 | s->dma_map_count += qiov->size; | |
1000 | ||
1001 | assert(entries <= s->page_size / sizeof(uint64_t)); | |
1002 | switch (entries) { | |
1003 | case 0: | |
1004 | abort(); | |
1005 | case 1: | |
c26f2173 KJ |
1006 | cmd->dptr.prp1 = pagelist[0]; |
1007 | cmd->dptr.prp2 = 0; | |
bdd6a90a FZ |
1008 | break; |
1009 | case 2: | |
c26f2173 KJ |
1010 | cmd->dptr.prp1 = pagelist[0]; |
1011 | cmd->dptr.prp2 = pagelist[1]; | |
bdd6a90a FZ |
1012 | break; |
1013 | default: | |
c26f2173 KJ |
1014 | cmd->dptr.prp1 = pagelist[0]; |
1015 | cmd->dptr.prp2 = cpu_to_le64(req->prp_list_iova + sizeof(uint64_t)); | |
bdd6a90a FZ |
1016 | break; |
1017 | } | |
1018 | trace_nvme_cmd_map_qiov(s, cmd, req, qiov, entries); | |
1019 | for (i = 0; i < entries; ++i) { | |
1020 | trace_nvme_cmd_map_qiov_pages(s, i, pagelist[i]); | |
1021 | } | |
1022 | return 0; | |
1023 | fail: | |
1024 | /* No need to unmap [0 - i) iovs even if we've failed, since we don't | |
1025 | * increment s->dma_map_count. This is okay for fixed mapping memory areas | |
1026 | * because they are already mapped before calling this function; for | |
1027 | * temporary mappings, a later nvme_cmd_(un)map_qiov will reclaim by | |
1028 | * calling qemu_vfio_dma_reset_temporary when necessary. */ | |
1029 | return r; | |
1030 | } | |
1031 | ||
1032 | typedef struct { | |
1033 | Coroutine *co; | |
1034 | int ret; | |
1035 | AioContext *ctx; | |
1036 | } NVMeCoData; | |
1037 | ||
1038 | static void nvme_rw_cb_bh(void *opaque) | |
1039 | { | |
1040 | NVMeCoData *data = opaque; | |
1041 | qemu_coroutine_enter(data->co); | |
1042 | } | |
1043 | ||
1044 | static void nvme_rw_cb(void *opaque, int ret) | |
1045 | { | |
1046 | NVMeCoData *data = opaque; | |
1047 | data->ret = ret; | |
1048 | if (!data->co) { | |
1049 | /* The rw coroutine hasn't yielded, don't try to enter. */ | |
1050 | return; | |
1051 | } | |
e4ec5ad4 | 1052 | replay_bh_schedule_oneshot_event(data->ctx, nvme_rw_cb_bh, data); |
bdd6a90a FZ |
1053 | } |
1054 | ||
1055 | static coroutine_fn int nvme_co_prw_aligned(BlockDriverState *bs, | |
1056 | uint64_t offset, uint64_t bytes, | |
1057 | QEMUIOVector *qiov, | |
1058 | bool is_write, | |
1059 | int flags) | |
1060 | { | |
1061 | int r; | |
1062 | BDRVNVMeState *s = bs->opaque; | |
73159e52 | 1063 | NVMeQueuePair *ioq = s->queues[INDEX_IO(0)]; |
bdd6a90a | 1064 | NVMeRequest *req; |
118d1b6a ML |
1065 | |
1066 | uint32_t cdw12 = (((bytes >> s->blkshift) - 1) & 0xFFFF) | | |
bdd6a90a FZ |
1067 | (flags & BDRV_REQ_FUA ? 1 << 30 : 0); |
1068 | NvmeCmd cmd = { | |
1069 | .opcode = is_write ? NVME_CMD_WRITE : NVME_CMD_READ, | |
1070 | .nsid = cpu_to_le32(s->nsid), | |
118d1b6a ML |
1071 | .cdw10 = cpu_to_le32((offset >> s->blkshift) & 0xFFFFFFFF), |
1072 | .cdw11 = cpu_to_le32(((offset >> s->blkshift) >> 32) & 0xFFFFFFFF), | |
bdd6a90a FZ |
1073 | .cdw12 = cpu_to_le32(cdw12), |
1074 | }; | |
1075 | NVMeCoData data = { | |
1076 | .ctx = bdrv_get_aio_context(bs), | |
1077 | .ret = -EINPROGRESS, | |
1078 | }; | |
1079 | ||
1080 | trace_nvme_prw_aligned(s, is_write, offset, bytes, flags, qiov->niov); | |
1081 | assert(s->nr_queues > 1); | |
1082 | req = nvme_get_free_req(ioq); | |
1083 | assert(req); | |
1084 | ||
1085 | qemu_co_mutex_lock(&s->dma_map_lock); | |
1086 | r = nvme_cmd_map_qiov(bs, &cmd, req, qiov); | |
1087 | qemu_co_mutex_unlock(&s->dma_map_lock); | |
1088 | if (r) { | |
b75fd5f5 | 1089 | nvme_put_free_req_and_wake(ioq, req); |
bdd6a90a FZ |
1090 | return r; |
1091 | } | |
b75fd5f5 | 1092 | nvme_submit_command(ioq, req, &cmd, nvme_rw_cb, &data); |
bdd6a90a FZ |
1093 | |
1094 | data.co = qemu_coroutine_self(); | |
1095 | while (data.ret == -EINPROGRESS) { | |
1096 | qemu_coroutine_yield(); | |
1097 | } | |
1098 | ||
1099 | qemu_co_mutex_lock(&s->dma_map_lock); | |
1100 | r = nvme_cmd_unmap_qiov(bs, qiov); | |
1101 | qemu_co_mutex_unlock(&s->dma_map_lock); | |
1102 | if (r) { | |
1103 | return r; | |
1104 | } | |
1105 | ||
1106 | trace_nvme_rw_done(s, is_write, offset, bytes, data.ret); | |
1107 | return data.ret; | |
1108 | } | |
1109 | ||
1110 | static inline bool nvme_qiov_aligned(BlockDriverState *bs, | |
1111 | const QEMUIOVector *qiov) | |
1112 | { | |
1113 | int i; | |
1114 | BDRVNVMeState *s = bs->opaque; | |
1115 | ||
1116 | for (i = 0; i < qiov->niov; ++i) { | |
1117 | if (!QEMU_PTR_IS_ALIGNED(qiov->iov[i].iov_base, s->page_size) || | |
1118 | !QEMU_IS_ALIGNED(qiov->iov[i].iov_len, s->page_size)) { | |
1119 | trace_nvme_qiov_unaligned(qiov, i, qiov->iov[i].iov_base, | |
1120 | qiov->iov[i].iov_len, s->page_size); | |
1121 | return false; | |
1122 | } | |
1123 | } | |
1124 | return true; | |
1125 | } | |
1126 | ||
1127 | static int nvme_co_prw(BlockDriverState *bs, uint64_t offset, uint64_t bytes, | |
1128 | QEMUIOVector *qiov, bool is_write, int flags) | |
1129 | { | |
1130 | BDRVNVMeState *s = bs->opaque; | |
1131 | int r; | |
1132 | uint8_t *buf = NULL; | |
1133 | QEMUIOVector local_qiov; | |
1134 | ||
1135 | assert(QEMU_IS_ALIGNED(offset, s->page_size)); | |
1136 | assert(QEMU_IS_ALIGNED(bytes, s->page_size)); | |
1137 | assert(bytes <= s->max_transfer); | |
1138 | if (nvme_qiov_aligned(bs, qiov)) { | |
1139 | return nvme_co_prw_aligned(bs, offset, bytes, qiov, is_write, flags); | |
1140 | } | |
1141 | trace_nvme_prw_buffered(s, offset, bytes, qiov->niov, is_write); | |
1142 | buf = qemu_try_blockalign(bs, bytes); | |
1143 | ||
1144 | if (!buf) { | |
1145 | return -ENOMEM; | |
1146 | } | |
1147 | qemu_iovec_init(&local_qiov, 1); | |
1148 | if (is_write) { | |
1149 | qemu_iovec_to_buf(qiov, 0, buf, bytes); | |
1150 | } | |
1151 | qemu_iovec_add(&local_qiov, buf, bytes); | |
1152 | r = nvme_co_prw_aligned(bs, offset, bytes, &local_qiov, is_write, flags); | |
1153 | qemu_iovec_destroy(&local_qiov); | |
1154 | if (!r && !is_write) { | |
1155 | qemu_iovec_from_buf(qiov, 0, buf, bytes); | |
1156 | } | |
1157 | qemu_vfree(buf); | |
1158 | return r; | |
1159 | } | |
1160 | ||
1161 | static coroutine_fn int nvme_co_preadv(BlockDriverState *bs, | |
1162 | uint64_t offset, uint64_t bytes, | |
1163 | QEMUIOVector *qiov, int flags) | |
1164 | { | |
1165 | return nvme_co_prw(bs, offset, bytes, qiov, false, flags); | |
1166 | } | |
1167 | ||
1168 | static coroutine_fn int nvme_co_pwritev(BlockDriverState *bs, | |
1169 | uint64_t offset, uint64_t bytes, | |
1170 | QEMUIOVector *qiov, int flags) | |
1171 | { | |
1172 | return nvme_co_prw(bs, offset, bytes, qiov, true, flags); | |
1173 | } | |
1174 | ||
1175 | static coroutine_fn int nvme_co_flush(BlockDriverState *bs) | |
1176 | { | |
1177 | BDRVNVMeState *s = bs->opaque; | |
73159e52 | 1178 | NVMeQueuePair *ioq = s->queues[INDEX_IO(0)]; |
bdd6a90a FZ |
1179 | NVMeRequest *req; |
1180 | NvmeCmd cmd = { | |
1181 | .opcode = NVME_CMD_FLUSH, | |
1182 | .nsid = cpu_to_le32(s->nsid), | |
1183 | }; | |
1184 | NVMeCoData data = { | |
1185 | .ctx = bdrv_get_aio_context(bs), | |
1186 | .ret = -EINPROGRESS, | |
1187 | }; | |
1188 | ||
1189 | assert(s->nr_queues > 1); | |
1190 | req = nvme_get_free_req(ioq); | |
1191 | assert(req); | |
b75fd5f5 | 1192 | nvme_submit_command(ioq, req, &cmd, nvme_rw_cb, &data); |
bdd6a90a FZ |
1193 | |
1194 | data.co = qemu_coroutine_self(); | |
1195 | if (data.ret == -EINPROGRESS) { | |
1196 | qemu_coroutine_yield(); | |
1197 | } | |
1198 | ||
1199 | return data.ret; | |
1200 | } | |
1201 | ||
1202 | ||
e0dd95e3 ML |
1203 | static coroutine_fn int nvme_co_pwrite_zeroes(BlockDriverState *bs, |
1204 | int64_t offset, | |
1205 | int bytes, | |
1206 | BdrvRequestFlags flags) | |
1207 | { | |
1208 | BDRVNVMeState *s = bs->opaque; | |
73159e52 | 1209 | NVMeQueuePair *ioq = s->queues[INDEX_IO(0)]; |
e0dd95e3 ML |
1210 | NVMeRequest *req; |
1211 | ||
1212 | uint32_t cdw12 = ((bytes >> s->blkshift) - 1) & 0xFFFF; | |
1213 | ||
1214 | if (!s->supports_write_zeroes) { | |
1215 | return -ENOTSUP; | |
1216 | } | |
1217 | ||
1218 | NvmeCmd cmd = { | |
69265150 | 1219 | .opcode = NVME_CMD_WRITE_ZEROES, |
e0dd95e3 ML |
1220 | .nsid = cpu_to_le32(s->nsid), |
1221 | .cdw10 = cpu_to_le32((offset >> s->blkshift) & 0xFFFFFFFF), | |
1222 | .cdw11 = cpu_to_le32(((offset >> s->blkshift) >> 32) & 0xFFFFFFFF), | |
1223 | }; | |
1224 | ||
1225 | NVMeCoData data = { | |
1226 | .ctx = bdrv_get_aio_context(bs), | |
1227 | .ret = -EINPROGRESS, | |
1228 | }; | |
1229 | ||
1230 | if (flags & BDRV_REQ_MAY_UNMAP) { | |
1231 | cdw12 |= (1 << 25); | |
1232 | } | |
1233 | ||
1234 | if (flags & BDRV_REQ_FUA) { | |
1235 | cdw12 |= (1 << 30); | |
1236 | } | |
1237 | ||
1238 | cmd.cdw12 = cpu_to_le32(cdw12); | |
1239 | ||
1240 | trace_nvme_write_zeroes(s, offset, bytes, flags); | |
1241 | assert(s->nr_queues > 1); | |
1242 | req = nvme_get_free_req(ioq); | |
1243 | assert(req); | |
1244 | ||
b75fd5f5 | 1245 | nvme_submit_command(ioq, req, &cmd, nvme_rw_cb, &data); |
e0dd95e3 ML |
1246 | |
1247 | data.co = qemu_coroutine_self(); | |
1248 | while (data.ret == -EINPROGRESS) { | |
1249 | qemu_coroutine_yield(); | |
1250 | } | |
1251 | ||
1252 | trace_nvme_rw_done(s, true, offset, bytes, data.ret); | |
1253 | return data.ret; | |
1254 | } | |
1255 | ||
1256 | ||
e87a09d6 ML |
1257 | static int coroutine_fn nvme_co_pdiscard(BlockDriverState *bs, |
1258 | int64_t offset, | |
1259 | int bytes) | |
1260 | { | |
1261 | BDRVNVMeState *s = bs->opaque; | |
73159e52 | 1262 | NVMeQueuePair *ioq = s->queues[INDEX_IO(0)]; |
e87a09d6 ML |
1263 | NVMeRequest *req; |
1264 | NvmeDsmRange *buf; | |
1265 | QEMUIOVector local_qiov; | |
1266 | int ret; | |
1267 | ||
1268 | NvmeCmd cmd = { | |
1269 | .opcode = NVME_CMD_DSM, | |
1270 | .nsid = cpu_to_le32(s->nsid), | |
1271 | .cdw10 = cpu_to_le32(0), /*number of ranges - 0 based*/ | |
1272 | .cdw11 = cpu_to_le32(1 << 2), /*deallocate bit*/ | |
1273 | }; | |
1274 | ||
1275 | NVMeCoData data = { | |
1276 | .ctx = bdrv_get_aio_context(bs), | |
1277 | .ret = -EINPROGRESS, | |
1278 | }; | |
1279 | ||
1280 | if (!s->supports_discard) { | |
1281 | return -ENOTSUP; | |
1282 | } | |
1283 | ||
1284 | assert(s->nr_queues > 1); | |
1285 | ||
1286 | buf = qemu_try_blockalign0(bs, s->page_size); | |
1287 | if (!buf) { | |
1288 | return -ENOMEM; | |
1289 | } | |
1290 | ||
1291 | buf->nlb = cpu_to_le32(bytes >> s->blkshift); | |
1292 | buf->slba = cpu_to_le64(offset >> s->blkshift); | |
1293 | buf->cattr = 0; | |
1294 | ||
1295 | qemu_iovec_init(&local_qiov, 1); | |
1296 | qemu_iovec_add(&local_qiov, buf, 4096); | |
1297 | ||
1298 | req = nvme_get_free_req(ioq); | |
1299 | assert(req); | |
1300 | ||
1301 | qemu_co_mutex_lock(&s->dma_map_lock); | |
1302 | ret = nvme_cmd_map_qiov(bs, &cmd, req, &local_qiov); | |
1303 | qemu_co_mutex_unlock(&s->dma_map_lock); | |
1304 | ||
1305 | if (ret) { | |
b75fd5f5 | 1306 | nvme_put_free_req_and_wake(ioq, req); |
e87a09d6 ML |
1307 | goto out; |
1308 | } | |
1309 | ||
1310 | trace_nvme_dsm(s, offset, bytes); | |
1311 | ||
b75fd5f5 | 1312 | nvme_submit_command(ioq, req, &cmd, nvme_rw_cb, &data); |
e87a09d6 ML |
1313 | |
1314 | data.co = qemu_coroutine_self(); | |
1315 | while (data.ret == -EINPROGRESS) { | |
1316 | qemu_coroutine_yield(); | |
1317 | } | |
1318 | ||
1319 | qemu_co_mutex_lock(&s->dma_map_lock); | |
1320 | ret = nvme_cmd_unmap_qiov(bs, &local_qiov); | |
1321 | qemu_co_mutex_unlock(&s->dma_map_lock); | |
1322 | ||
1323 | if (ret) { | |
1324 | goto out; | |
1325 | } | |
1326 | ||
1327 | ret = data.ret; | |
1328 | trace_nvme_dsm_done(s, offset, bytes, ret); | |
1329 | out: | |
1330 | qemu_iovec_destroy(&local_qiov); | |
1331 | qemu_vfree(buf); | |
1332 | return ret; | |
1333 | ||
1334 | } | |
1335 | ||
1336 | ||
bdd6a90a FZ |
1337 | static int nvme_reopen_prepare(BDRVReopenState *reopen_state, |
1338 | BlockReopenQueue *queue, Error **errp) | |
1339 | { | |
1340 | return 0; | |
1341 | } | |
1342 | ||
998b3a1e | 1343 | static void nvme_refresh_filename(BlockDriverState *bs) |
bdd6a90a | 1344 | { |
cc61b074 | 1345 | BDRVNVMeState *s = bs->opaque; |
bdd6a90a | 1346 | |
cc61b074 HR |
1347 | snprintf(bs->exact_filename, sizeof(bs->exact_filename), "nvme://%s/%i", |
1348 | s->device, s->nsid); | |
bdd6a90a FZ |
1349 | } |
1350 | ||
1351 | static void nvme_refresh_limits(BlockDriverState *bs, Error **errp) | |
1352 | { | |
1353 | BDRVNVMeState *s = bs->opaque; | |
1354 | ||
1355 | bs->bl.opt_mem_alignment = s->page_size; | |
1356 | bs->bl.request_alignment = s->page_size; | |
1357 | bs->bl.max_transfer = s->max_transfer; | |
1358 | } | |
1359 | ||
1360 | static void nvme_detach_aio_context(BlockDriverState *bs) | |
1361 | { | |
1362 | BDRVNVMeState *s = bs->opaque; | |
1363 | ||
7838c67f SH |
1364 | for (int i = 0; i < s->nr_queues; i++) { |
1365 | NVMeQueuePair *q = s->queues[i]; | |
1366 | ||
1367 | qemu_bh_delete(q->completion_bh); | |
1368 | q->completion_bh = NULL; | |
1369 | } | |
1370 | ||
bdd6a90a FZ |
1371 | aio_set_event_notifier(bdrv_get_aio_context(bs), &s->irq_notifier, |
1372 | false, NULL, NULL); | |
1373 | } | |
1374 | ||
1375 | static void nvme_attach_aio_context(BlockDriverState *bs, | |
1376 | AioContext *new_context) | |
1377 | { | |
1378 | BDRVNVMeState *s = bs->opaque; | |
1379 | ||
1380 | s->aio_context = new_context; | |
1381 | aio_set_event_notifier(new_context, &s->irq_notifier, | |
1382 | false, nvme_handle_event, nvme_poll_cb); | |
7838c67f SH |
1383 | |
1384 | for (int i = 0; i < s->nr_queues; i++) { | |
1385 | NVMeQueuePair *q = s->queues[i]; | |
1386 | ||
1387 | q->completion_bh = | |
1388 | aio_bh_new(new_context, nvme_process_completion_bh, q); | |
1389 | } | |
bdd6a90a FZ |
1390 | } |
1391 | ||
1392 | static void nvme_aio_plug(BlockDriverState *bs) | |
1393 | { | |
1394 | BDRVNVMeState *s = bs->opaque; | |
2f0d8947 PB |
1395 | assert(!s->plugged); |
1396 | s->plugged = true; | |
bdd6a90a FZ |
1397 | } |
1398 | ||
1399 | static void nvme_aio_unplug(BlockDriverState *bs) | |
1400 | { | |
1401 | int i; | |
1402 | BDRVNVMeState *s = bs->opaque; | |
1403 | assert(s->plugged); | |
2f0d8947 | 1404 | s->plugged = false; |
73159e52 | 1405 | for (i = INDEX_IO(0); i < s->nr_queues; i++) { |
2f0d8947 PB |
1406 | NVMeQueuePair *q = s->queues[i]; |
1407 | qemu_mutex_lock(&q->lock); | |
b75fd5f5 SH |
1408 | nvme_kick(q); |
1409 | nvme_process_completion(q); | |
2f0d8947 | 1410 | qemu_mutex_unlock(&q->lock); |
bdd6a90a FZ |
1411 | } |
1412 | } | |
1413 | ||
9ed61612 FZ |
1414 | static void nvme_register_buf(BlockDriverState *bs, void *host, size_t size) |
1415 | { | |
1416 | int ret; | |
1417 | BDRVNVMeState *s = bs->opaque; | |
1418 | ||
1419 | ret = qemu_vfio_dma_map(s->vfio, host, size, false, NULL); | |
1420 | if (ret) { | |
1421 | /* FIXME: we may run out of IOVA addresses after repeated | |
1422 | * bdrv_register_buf/bdrv_unregister_buf, because nvme_vfio_dma_unmap | |
1423 | * doesn't reclaim addresses for fixed mappings. */ | |
1424 | error_report("nvme_register_buf failed: %s", strerror(-ret)); | |
1425 | } | |
1426 | } | |
1427 | ||
1428 | static void nvme_unregister_buf(BlockDriverState *bs, void *host) | |
1429 | { | |
1430 | BDRVNVMeState *s = bs->opaque; | |
1431 | ||
1432 | qemu_vfio_dma_unmap(s->vfio, host); | |
1433 | } | |
1434 | ||
2654267c HR |
1435 | static const char *const nvme_strong_runtime_opts[] = { |
1436 | NVME_BLOCK_OPT_DEVICE, | |
1437 | NVME_BLOCK_OPT_NAMESPACE, | |
1438 | ||
1439 | NULL | |
1440 | }; | |
1441 | ||
bdd6a90a FZ |
1442 | static BlockDriver bdrv_nvme = { |
1443 | .format_name = "nvme", | |
1444 | .protocol_name = "nvme", | |
1445 | .instance_size = sizeof(BDRVNVMeState), | |
1446 | ||
5a5e7f8c ML |
1447 | .bdrv_co_create_opts = bdrv_co_create_opts_simple, |
1448 | .create_opts = &bdrv_create_opts_simple, | |
1449 | ||
bdd6a90a FZ |
1450 | .bdrv_parse_filename = nvme_parse_filename, |
1451 | .bdrv_file_open = nvme_file_open, | |
1452 | .bdrv_close = nvme_close, | |
1453 | .bdrv_getlength = nvme_getlength, | |
118d1b6a | 1454 | .bdrv_probe_blocksizes = nvme_probe_blocksizes, |
bdd6a90a FZ |
1455 | |
1456 | .bdrv_co_preadv = nvme_co_preadv, | |
1457 | .bdrv_co_pwritev = nvme_co_pwritev, | |
e0dd95e3 ML |
1458 | |
1459 | .bdrv_co_pwrite_zeroes = nvme_co_pwrite_zeroes, | |
e87a09d6 | 1460 | .bdrv_co_pdiscard = nvme_co_pdiscard, |
e0dd95e3 | 1461 | |
bdd6a90a FZ |
1462 | .bdrv_co_flush_to_disk = nvme_co_flush, |
1463 | .bdrv_reopen_prepare = nvme_reopen_prepare, | |
1464 | ||
bdd6a90a FZ |
1465 | .bdrv_refresh_filename = nvme_refresh_filename, |
1466 | .bdrv_refresh_limits = nvme_refresh_limits, | |
2654267c | 1467 | .strong_runtime_opts = nvme_strong_runtime_opts, |
bdd6a90a FZ |
1468 | |
1469 | .bdrv_detach_aio_context = nvme_detach_aio_context, | |
1470 | .bdrv_attach_aio_context = nvme_attach_aio_context, | |
1471 | ||
1472 | .bdrv_io_plug = nvme_aio_plug, | |
1473 | .bdrv_io_unplug = nvme_aio_unplug, | |
9ed61612 FZ |
1474 | |
1475 | .bdrv_register_buf = nvme_register_buf, | |
1476 | .bdrv_unregister_buf = nvme_unregister_buf, | |
bdd6a90a FZ |
1477 | }; |
1478 | ||
1479 | static void bdrv_nvme_init(void) | |
1480 | { | |
1481 | bdrv_register(&bdrv_nvme); | |
1482 | } | |
1483 | ||
1484 | block_init(bdrv_nvme_init); |