]> git.proxmox.com Git - mirror_qemu.git/blame - hw/block/virtio-blk.c
block: explicitly acquire aiocontext in bottom halves that need it
[mirror_qemu.git] / hw / block / virtio-blk.c
CommitLineData
6e02c38d
AL
1/*
2 * Virtio Block Device
3 *
4 * Copyright IBM, Corp. 2007
5 *
6 * Authors:
7 * Anthony Liguori <aliguori@us.ibm.com>
8 *
9 * This work is licensed under the terms of the GNU GPL, version 2. See
10 * the COPYING file in the top-level directory.
11 *
12 */
13
80c71a24 14#include "qemu/osdep.h"
da34e65c 15#include "qapi/error.h"
5a61cb60 16#include "qemu-common.h"
827805a2 17#include "qemu/iov.h"
1de7afc9 18#include "qemu/error-report.h"
6d519a5f 19#include "trace.h"
0d09e41a 20#include "hw/block/block.h"
4be74634 21#include "sysemu/block-backend.h"
9c17d615 22#include "sysemu/blockdev.h"
0d09e41a 23#include "hw/virtio/virtio-blk.h"
52b53c04 24#include "dataplane/virtio-blk.h"
0d09e41a 25#include "block/scsi.h"
1063b8b1
CH
26#ifdef __linux__
27# include <scsi/sg.h>
28#endif
0d09e41a 29#include "hw/virtio/virtio-bus.h"
783d1897 30#include "hw/virtio/virtio-access.h"
6e02c38d 31
d14dde5e
GK
32static void virtio_blk_init_request(VirtIOBlock *s, VirtQueue *vq,
33 VirtIOBlockReq *req)
671ec3f0 34{
671ec3f0 35 req->dev = s;
edaffd9f 36 req->vq = vq;
869d66af 37 req->qiov.size = 0;
2a6cdd6d 38 req->in_len = 0;
869d66af 39 req->next = NULL;
95f7142a 40 req->mr_next = NULL;
671ec3f0
FZ
41}
42
d14dde5e 43static void virtio_blk_free_request(VirtIOBlockReq *req)
671ec3f0
FZ
44{
45 if (req) {
c84b3192 46 g_free(req);
671ec3f0
FZ
47 }
48}
49
03de2f52 50static void virtio_blk_req_complete(VirtIOBlockReq *req, unsigned char status)
869a5c6d
AL
51{
52 VirtIOBlock *s = req->dev;
1cc91b7d 53 VirtIODevice *vdev = VIRTIO_DEVICE(s);
869a5c6d 54
6d519a5f
SH
55 trace_virtio_blk_req_complete(req, status);
56
92e3c2a3 57 stb_p(&req->in->status, status);
edaffd9f 58 virtqueue_push(req->vq, &req->elem, req->in_len);
eb41cf78 59 if (s->dataplane_started && !s->dataplane_disabled) {
edaffd9f 60 virtio_blk_data_plane_notify(s->dataplane, req->vq);
03de2f52 61 } else {
edaffd9f 62 virtio_notify(vdev, req->vq);
03de2f52 63 }
bf4bd461
FZ
64}
65
f35d68f0 66static int virtio_blk_handle_rw_error(VirtIOBlockReq *req, int error,
1ceee0d5 67 bool is_read)
869a5c6d 68{
4be74634
MA
69 BlockErrorAction action = blk_get_error_action(req->dev->blk,
70 is_read, error);
869a5c6d
AL
71 VirtIOBlock *s = req->dev;
72
a589569f 73 if (action == BLOCK_ERROR_ACTION_STOP) {
466138dc
FZ
74 /* Break the link as the next request is going to be parsed from the
75 * ring again. Otherwise we may end up doing a double completion! */
76 req->mr_next = NULL;
869a5c6d
AL
77 req->next = s->rq;
78 s->rq = req;
a589569f 79 } else if (action == BLOCK_ERROR_ACTION_REPORT) {
869a5c6d 80 virtio_blk_req_complete(req, VIRTIO_BLK_S_IOERR);
01762e03 81 block_acct_failed(blk_get_stats(s->blk), &req->acct);
671ec3f0 82 virtio_blk_free_request(req);
869a5c6d
AL
83 }
84
4be74634 85 blk_error_action(s->blk, action, is_read, error);
a589569f 86 return action != BLOCK_ERROR_ACTION_IGNORE;
869a5c6d
AL
87}
88
6e02c38d
AL
89static void virtio_blk_rw_complete(void *opaque, int ret)
90{
95f7142a
PL
91 VirtIOBlockReq *next = opaque;
92
93 while (next) {
94 VirtIOBlockReq *req = next;
95 next = req->mr_next;
96 trace_virtio_blk_rw_complete(req, ret);
97
98 if (req->qiov.nalloc != -1) {
99 /* If nalloc is != 1 req->qiov is a local copy of the original
100 * external iovec. It was allocated in submit_merged_requests
101 * to be able to merge requests. */
102 qemu_iovec_destroy(&req->qiov);
103 }
6e02c38d 104
95f7142a
PL
105 if (ret) {
106 int p = virtio_ldl_p(VIRTIO_DEVICE(req->dev), &req->out.type);
107 bool is_read = !(p & VIRTIO_BLK_T_OUT);
2a6cdd6d
PB
108 /* Note that memory may be dirtied on read failure. If the
109 * virtio request is not completed here, as is the case for
110 * BLOCK_ERROR_ACTION_STOP, the memory may not be copied
111 * correctly during live migration. While this is ugly,
112 * it is acceptable because the device is free to write to
113 * the memory until the request is completed (which will
114 * happen on the other side of the migration).
115 */
95f7142a
PL
116 if (virtio_blk_handle_rw_error(req, -ret, is_read)) {
117 continue;
118 }
119 }
6d519a5f 120
95f7142a
PL
121 virtio_blk_req_complete(req, VIRTIO_BLK_S_OK);
122 block_acct_done(blk_get_stats(req->dev->blk), &req->acct);
123 virtio_blk_free_request(req);
6e02c38d 124 }
869a5c6d 125}
6e02c38d 126
aa659be3
CH
127static void virtio_blk_flush_complete(void *opaque, int ret)
128{
129 VirtIOBlockReq *req = opaque;
130
8c269b54
KW
131 if (ret) {
132 if (virtio_blk_handle_rw_error(req, -ret, 0)) {
133 return;
134 }
135 }
136
137 virtio_blk_req_complete(req, VIRTIO_BLK_S_OK);
4be74634 138 block_acct_done(blk_get_stats(req->dev->blk), &req->acct);
671ec3f0 139 virtio_blk_free_request(req);
6e02c38d
AL
140}
141
1dc936aa
FZ
142#ifdef __linux__
143
144typedef struct {
145 VirtIOBlockReq *req;
146 struct sg_io_hdr hdr;
147} VirtIOBlockIoctlReq;
148
149static void virtio_blk_ioctl_complete(void *opaque, int status)
150{
151 VirtIOBlockIoctlReq *ioctl_req = opaque;
152 VirtIOBlockReq *req = ioctl_req->req;
9d456654
PB
153 VirtIOBlock *s = req->dev;
154 VirtIODevice *vdev = VIRTIO_DEVICE(s);
1dc936aa
FZ
155 struct virtio_scsi_inhdr *scsi;
156 struct sg_io_hdr *hdr;
157
158 scsi = (void *)req->elem.in_sg[req->elem.in_num - 2].iov_base;
159
160 if (status) {
161 status = VIRTIO_BLK_S_UNSUPP;
162 virtio_stl_p(vdev, &scsi->errors, 255);
163 goto out;
164 }
165
166 hdr = &ioctl_req->hdr;
167 /*
168 * From SCSI-Generic-HOWTO: "Some lower level drivers (e.g. ide-scsi)
169 * clear the masked_status field [hence status gets cleared too, see
170 * block/scsi_ioctl.c] even when a CHECK_CONDITION or COMMAND_TERMINATED
171 * status has occurred. However they do set DRIVER_SENSE in driver_status
172 * field. Also a (sb_len_wr > 0) indicates there is a sense buffer.
173 */
174 if (hdr->status == 0 && hdr->sb_len_wr > 0) {
175 hdr->status = CHECK_CONDITION;
176 }
177
178 virtio_stl_p(vdev, &scsi->errors,
179 hdr->status | (hdr->msg_status << 8) |
180 (hdr->host_status << 16) | (hdr->driver_status << 24));
181 virtio_stl_p(vdev, &scsi->residual, hdr->resid);
182 virtio_stl_p(vdev, &scsi->sense_len, hdr->sb_len_wr);
183 virtio_stl_p(vdev, &scsi->data_len, hdr->dxfer_len);
184
185out:
186 virtio_blk_req_complete(req, status);
187 virtio_blk_free_request(req);
188 g_free(ioctl_req);
189}
190
191#endif
192
edaffd9f 193static VirtIOBlockReq *virtio_blk_get_request(VirtIOBlock *s, VirtQueue *vq)
6e02c38d 194{
edaffd9f 195 VirtIOBlockReq *req = virtqueue_pop(vq, sizeof(VirtIOBlockReq));
6e02c38d 196
51b19ebe 197 if (req) {
edaffd9f 198 virtio_blk_init_request(s, vq, req);
6e02c38d 199 }
6e02c38d
AL
200 return req;
201}
202
75344fa4 203static int virtio_blk_handle_scsi_req(VirtIOBlockReq *req)
1063b8b1 204{
5a05cbee
FZ
205 int status = VIRTIO_BLK_S_OK;
206 struct virtio_scsi_inhdr *scsi = NULL;
75344fa4
FZ
207 VirtIODevice *vdev = VIRTIO_DEVICE(req->dev);
208 VirtQueueElement *elem = &req->elem;
209 VirtIOBlock *blk = req->dev;
783d1897 210
47ce9ef7 211#ifdef __linux__
1063b8b1 212 int i;
1dc936aa 213 VirtIOBlockIoctlReq *ioctl_req;
a209f461 214 BlockAIOCB *acb;
47ce9ef7 215#endif
1063b8b1
CH
216
217 /*
218 * We require at least one output segment each for the virtio_blk_outhdr
219 * and the SCSI command block.
220 *
221 * We also at least require the virtio_blk_inhdr, the virtio_scsi_inhdr
222 * and the sense buffer pointer in the input segments.
223 */
5a05cbee
FZ
224 if (elem->out_num < 2 || elem->in_num < 3) {
225 status = VIRTIO_BLK_S_IOERR;
226 goto fail;
1063b8b1
CH
227 }
228
229 /*
f34e73cd
PB
230 * The scsi inhdr is placed in the second-to-last input segment, just
231 * before the regular inhdr.
1063b8b1 232 */
5a05cbee 233 scsi = (void *)elem->in_sg[elem->in_num - 2].iov_base;
f34e73cd 234
2a30307f 235 if (!blk->conf.scsi) {
f34e73cd
PB
236 status = VIRTIO_BLK_S_UNSUPP;
237 goto fail;
1063b8b1
CH
238 }
239
240 /*
f34e73cd 241 * No support for bidirection commands yet.
1063b8b1 242 */
5a05cbee 243 if (elem->out_num > 2 && elem->in_num > 3) {
f34e73cd
PB
244 status = VIRTIO_BLK_S_UNSUPP;
245 goto fail;
246 }
1063b8b1 247
f34e73cd 248#ifdef __linux__
1dc936aa
FZ
249 ioctl_req = g_new0(VirtIOBlockIoctlReq, 1);
250 ioctl_req->req = req;
251 ioctl_req->hdr.interface_id = 'S';
252 ioctl_req->hdr.cmd_len = elem->out_sg[1].iov_len;
253 ioctl_req->hdr.cmdp = elem->out_sg[1].iov_base;
254 ioctl_req->hdr.dxfer_len = 0;
1063b8b1 255
5a05cbee 256 if (elem->out_num > 2) {
1063b8b1
CH
257 /*
258 * If there are more than the minimally required 2 output segments
259 * there is write payload starting from the third iovec.
260 */
1dc936aa
FZ
261 ioctl_req->hdr.dxfer_direction = SG_DXFER_TO_DEV;
262 ioctl_req->hdr.iovec_count = elem->out_num - 2;
1063b8b1 263
1dc936aa
FZ
264 for (i = 0; i < ioctl_req->hdr.iovec_count; i++) {
265 ioctl_req->hdr.dxfer_len += elem->out_sg[i + 2].iov_len;
266 }
1063b8b1 267
1dc936aa 268 ioctl_req->hdr.dxferp = elem->out_sg + 2;
1063b8b1 269
5a05cbee 270 } else if (elem->in_num > 3) {
1063b8b1
CH
271 /*
272 * If we have more than 3 input segments the guest wants to actually
273 * read data.
274 */
1dc936aa
FZ
275 ioctl_req->hdr.dxfer_direction = SG_DXFER_FROM_DEV;
276 ioctl_req->hdr.iovec_count = elem->in_num - 3;
277 for (i = 0; i < ioctl_req->hdr.iovec_count; i++) {
278 ioctl_req->hdr.dxfer_len += elem->in_sg[i].iov_len;
279 }
1063b8b1 280
1dc936aa 281 ioctl_req->hdr.dxferp = elem->in_sg;
1063b8b1
CH
282 } else {
283 /*
284 * Some SCSI commands don't actually transfer any data.
285 */
1dc936aa 286 ioctl_req->hdr.dxfer_direction = SG_DXFER_NONE;
1063b8b1
CH
287 }
288
1dc936aa
FZ
289 ioctl_req->hdr.sbp = elem->in_sg[elem->in_num - 3].iov_base;
290 ioctl_req->hdr.mx_sb_len = elem->in_sg[elem->in_num - 3].iov_len;
1063b8b1 291
a209f461
FZ
292 acb = blk_aio_ioctl(blk->blk, SG_IO, &ioctl_req->hdr,
293 virtio_blk_ioctl_complete, ioctl_req);
294 if (!acb) {
295 g_free(ioctl_req);
296 status = VIRTIO_BLK_S_UNSUPP;
297 goto fail;
298 }
1dc936aa 299 return -EINPROGRESS;
1063b8b1 300#else
f34e73cd
PB
301 abort();
302#endif
303
304fail:
305 /* Just put anything nonzero so that the ioctl fails in the guest. */
5a05cbee 306 if (scsi) {
783d1897 307 virtio_stl_p(vdev, &scsi->errors, 255);
5a05cbee
FZ
308 }
309 return status;
310}
311
312static void virtio_blk_handle_scsi(VirtIOBlockReq *req)
313{
314 int status;
315
75344fa4 316 status = virtio_blk_handle_scsi_req(req);
1dc936aa
FZ
317 if (status != -EINPROGRESS) {
318 virtio_blk_req_complete(req, status);
319 virtio_blk_free_request(req);
320 }
1063b8b1 321}
1063b8b1 322
95f7142a
PL
323static inline void submit_requests(BlockBackend *blk, MultiReqBuffer *mrb,
324 int start, int num_reqs, int niov)
869a5c6d 325{
95f7142a
PL
326 QEMUIOVector *qiov = &mrb->reqs[start]->qiov;
327 int64_t sector_num = mrb->reqs[start]->sector_num;
95f7142a
PL
328 bool is_write = mrb->is_write;
329
330 if (num_reqs > 1) {
331 int i;
332 struct iovec *tmp_iov = qiov->iov;
333 int tmp_niov = qiov->niov;
334
335 /* mrb->reqs[start]->qiov was initialized from external so we can't
b5772fdd 336 * modify it here. We need to initialize it locally and then add the
95f7142a
PL
337 * external iovecs. */
338 qemu_iovec_init(qiov, niov);
339
340 for (i = 0; i < tmp_niov; i++) {
341 qemu_iovec_add(qiov, tmp_iov[i].iov_base, tmp_iov[i].iov_len);
342 }
343
344 for (i = start + 1; i < start + num_reqs; i++) {
345 qemu_iovec_concat(qiov, &mrb->reqs[i]->qiov, 0,
346 mrb->reqs[i]->qiov.size);
347 mrb->reqs[i - 1]->mr_next = mrb->reqs[i];
95f7142a 348 }
95f7142a 349
b5772fdd
EB
350 trace_virtio_blk_submit_multireq(mrb, start, num_reqs,
351 sector_num << BDRV_SECTOR_BITS,
352 qiov->size, is_write);
95f7142a
PL
353 block_acct_merge_done(blk_get_stats(blk),
354 is_write ? BLOCK_ACCT_WRITE : BLOCK_ACCT_READ,
355 num_reqs - 1);
356 }
91553dcc 357
95f7142a 358 if (is_write) {
b5772fdd
EB
359 blk_aio_pwritev(blk, sector_num << BDRV_SECTOR_BITS, qiov, 0,
360 virtio_blk_rw_complete, mrb->reqs[start]);
95f7142a 361 } else {
b5772fdd
EB
362 blk_aio_preadv(blk, sector_num << BDRV_SECTOR_BITS, qiov, 0,
363 virtio_blk_rw_complete, mrb->reqs[start]);
95f7142a
PL
364 }
365}
366
367static int multireq_compare(const void *a, const void *b)
368{
369 const VirtIOBlockReq *req1 = *(VirtIOBlockReq **)a,
370 *req2 = *(VirtIOBlockReq **)b;
371
372 /*
373 * Note that we can't simply subtract sector_num1 from sector_num2
374 * here as that could overflow the return value.
375 */
376 if (req1->sector_num > req2->sector_num) {
377 return 1;
378 } else if (req1->sector_num < req2->sector_num) {
379 return -1;
380 } else {
381 return 0;
382 }
383}
384
d14dde5e 385static void virtio_blk_submit_multireq(BlockBackend *blk, MultiReqBuffer *mrb)
95f7142a
PL
386{
387 int i = 0, start = 0, num_reqs = 0, niov = 0, nb_sectors = 0;
5def6b80 388 uint32_t max_transfer;
95f7142a
PL
389 int64_t sector_num = 0;
390
391 if (mrb->num_reqs == 1) {
392 submit_requests(blk, mrb, 0, 1, -1);
393 mrb->num_reqs = 0;
c20fd872
CH
394 return;
395 }
396
5def6b80 397 max_transfer = blk_get_max_transfer(mrb->reqs[0]->dev->blk);
95f7142a
PL
398
399 qsort(mrb->reqs, mrb->num_reqs, sizeof(*mrb->reqs),
400 &multireq_compare);
401
402 for (i = 0; i < mrb->num_reqs; i++) {
403 VirtIOBlockReq *req = mrb->reqs[i];
404 if (num_reqs > 0) {
49cffbc6
GA
405 /*
406 * NOTE: We cannot merge the requests in below situations:
407 * 1. requests are not sequential
408 * 2. merge would exceed maximum number of IOVs
409 * 3. merge would exceed maximum transfer length of backend device
410 */
411 if (sector_num + nb_sectors != req->sector_num ||
222565f6 412 niov > blk_get_max_iov(blk) - req->qiov.niov ||
5def6b80
EB
413 req->qiov.size > max_transfer ||
414 nb_sectors > (max_transfer -
415 req->qiov.size) / BDRV_SECTOR_SIZE) {
95f7142a
PL
416 submit_requests(blk, mrb, start, num_reqs, niov);
417 num_reqs = 0;
91553dcc
KW
418 }
419 }
95f7142a
PL
420
421 if (num_reqs == 0) {
422 sector_num = req->sector_num;
423 nb_sectors = niov = 0;
424 start = i;
425 }
426
427 nb_sectors += req->qiov.size / BDRV_SECTOR_SIZE;
428 niov += req->qiov.niov;
429 num_reqs++;
91553dcc 430 }
c20fd872 431
95f7142a
PL
432 submit_requests(blk, mrb, start, num_reqs, niov);
433 mrb->num_reqs = 0;
91553dcc 434}
87b245db 435
c20fd872 436static void virtio_blk_handle_flush(VirtIOBlockReq *req, MultiReqBuffer *mrb)
aa659be3 437{
4be74634 438 block_acct_start(blk_get_stats(req->dev->blk), &req->acct, 0,
5366d0c8 439 BLOCK_ACCT_FLUSH);
a597e79c 440
618fbb84
CH
441 /*
442 * Make sure all outstanding writes are posted to the backing device.
443 */
95f7142a
PL
444 if (mrb->is_write && mrb->num_reqs > 0) {
445 virtio_blk_submit_multireq(req->dev->blk, mrb);
446 }
4be74634 447 blk_aio_flush(req->dev->blk, virtio_blk_flush_complete, req);
aa659be3
CH
448}
449
d0e14376
MA
450static bool virtio_blk_sect_range_ok(VirtIOBlock *dev,
451 uint64_t sector, size_t size)
452{
3c2daac0
MA
453 uint64_t nb_sectors = size >> BDRV_SECTOR_BITS;
454 uint64_t total_sectors;
455
75af1f34 456 if (nb_sectors > BDRV_REQUEST_MAX_SECTORS) {
95f7142a
PL
457 return false;
458 }
d0e14376
MA
459 if (sector & dev->sector_mask) {
460 return false;
461 }
2a30307f 462 if (size % dev->conf.conf.logical_block_size) {
d0e14376
MA
463 return false;
464 }
4be74634 465 blk_get_geometry(dev->blk, &total_sectors);
3c2daac0
MA
466 if (sector > total_sectors || nb_sectors > total_sectors - sector) {
467 return false;
468 }
d0e14376
MA
469 return true;
470}
471
20ea686a 472static int virtio_blk_handle_request(VirtIOBlockReq *req, MultiReqBuffer *mrb)
bc6694d4 473{
92e3c2a3 474 uint32_t type;
f897bf75
SH
475 struct iovec *in_iov = req->elem.in_sg;
476 struct iovec *iov = req->elem.out_sg;
477 unsigned in_num = req->elem.in_num;
478 unsigned out_num = req->elem.out_num;
20ea686a
GK
479 VirtIOBlock *s = req->dev;
480 VirtIODevice *vdev = VIRTIO_DEVICE(s);
92e3c2a3 481
f897bf75 482 if (req->elem.out_num < 1 || req->elem.in_num < 1) {
20ea686a
GK
483 virtio_error(vdev, "virtio-blk missing headers");
484 return -1;
bc6694d4
KW
485 }
486
827805a2
FZ
487 if (unlikely(iov_to_buf(iov, out_num, 0, &req->out,
488 sizeof(req->out)) != sizeof(req->out))) {
20ea686a
GK
489 virtio_error(vdev, "virtio-blk request outhdr too short");
490 return -1;
827805a2 491 }
ee17e848 492
827805a2 493 iov_discard_front(&iov, &out_num, sizeof(req->out));
ee17e848 494
12048545 495 if (in_iov[in_num - 1].iov_len < sizeof(struct virtio_blk_inhdr)) {
20ea686a
GK
496 virtio_error(vdev, "virtio-blk request inhdr too short");
497 return -1;
ee17e848
FZ
498 }
499
2a6cdd6d
PB
500 /* We always touch the last byte, so just see how big in_iov is. */
501 req->in_len = iov_size(in_iov, in_num);
ee17e848
FZ
502 req->in = (void *)in_iov[in_num - 1].iov_base
503 + in_iov[in_num - 1].iov_len
504 - sizeof(struct virtio_blk_inhdr);
505 iov_discard_back(in_iov, &in_num, sizeof(struct virtio_blk_inhdr));
bc6694d4 506
783d1897 507 type = virtio_ldl_p(VIRTIO_DEVICE(req->dev), &req->out.type);
92e3c2a3 508
95f7142a 509 /* VIRTIO_BLK_T_OUT defines the command direction. VIRTIO_BLK_T_BARRIER
631b22ea 510 * is an optional flag. Although a guest should not send this flag if
95f7142a
PL
511 * not negotiated we ignored it in the past. So keep ignoring it. */
512 switch (type & ~(VIRTIO_BLK_T_OUT | VIRTIO_BLK_T_BARRIER)) {
513 case VIRTIO_BLK_T_IN:
514 {
515 bool is_write = type & VIRTIO_BLK_T_OUT;
516 req->sector_num = virtio_ldq_p(VIRTIO_DEVICE(req->dev),
517 &req->out.sector);
518
519 if (is_write) {
520 qemu_iovec_init_external(&req->qiov, iov, out_num);
521 trace_virtio_blk_handle_write(req, req->sector_num,
522 req->qiov.size / BDRV_SECTOR_SIZE);
523 } else {
524 qemu_iovec_init_external(&req->qiov, in_iov, in_num);
525 trace_virtio_blk_handle_read(req, req->sector_num,
526 req->qiov.size / BDRV_SECTOR_SIZE);
527 }
528
529 if (!virtio_blk_sect_range_ok(req->dev, req->sector_num,
530 req->qiov.size)) {
531 virtio_blk_req_complete(req, VIRTIO_BLK_S_IOERR);
01762e03
AG
532 block_acct_invalid(blk_get_stats(req->dev->blk),
533 is_write ? BLOCK_ACCT_WRITE : BLOCK_ACCT_READ);
95f7142a 534 virtio_blk_free_request(req);
20ea686a 535 return 0;
95f7142a
PL
536 }
537
538 block_acct_start(blk_get_stats(req->dev->blk),
539 &req->acct, req->qiov.size,
540 is_write ? BLOCK_ACCT_WRITE : BLOCK_ACCT_READ);
541
542 /* merge would exceed maximum number of requests or IO direction
543 * changes */
544 if (mrb->num_reqs > 0 && (mrb->num_reqs == VIRTIO_BLK_MAX_MERGE_REQS ||
c99495ac
PL
545 is_write != mrb->is_write ||
546 !req->dev->conf.request_merging)) {
95f7142a
PL
547 virtio_blk_submit_multireq(req->dev->blk, mrb);
548 }
549
550 assert(mrb->num_reqs < VIRTIO_BLK_MAX_MERGE_REQS);
551 mrb->reqs[mrb->num_reqs++] = req;
552 mrb->is_write = is_write;
553 break;
554 }
555 case VIRTIO_BLK_T_FLUSH:
c20fd872 556 virtio_blk_handle_flush(req, mrb);
95f7142a
PL
557 break;
558 case VIRTIO_BLK_T_SCSI_CMD:
bc6694d4 559 virtio_blk_handle_scsi(req);
95f7142a
PL
560 break;
561 case VIRTIO_BLK_T_GET_ID:
562 {
2930b313 563 VirtIOBlock *s = req->dev;
564
a8686a9b
MA
565 /*
566 * NB: per existing s/n string convention the string is
567 * terminated by '\0' only when shorter than buffer.
568 */
2a30307f 569 const char *serial = s->conf.serial ? s->conf.serial : "";
a83ceea8
MM
570 size_t size = MIN(strlen(serial) + 1,
571 MIN(iov_size(in_iov, in_num),
572 VIRTIO_BLK_ID_BYTES));
573 iov_from_buf(in_iov, in_num, 0, serial, size);
2930b313 574 virtio_blk_req_complete(req, VIRTIO_BLK_S_OK);
671ec3f0 575 virtio_blk_free_request(req);
95f7142a
PL
576 break;
577 }
578 default:
9e72c450 579 virtio_blk_req_complete(req, VIRTIO_BLK_S_UNSUPP);
671ec3f0 580 virtio_blk_free_request(req);
bc6694d4 581 }
20ea686a 582 return 0;
bc6694d4
KW
583}
584
07931698 585bool virtio_blk_handle_vq(VirtIOBlock *s, VirtQueue *vq)
6e02c38d 586{
6e02c38d 587 VirtIOBlockReq *req;
95f7142a 588 MultiReqBuffer mrb = {};
07931698 589 bool progress = false;
6e02c38d 590
9d456654 591 aio_context_acquire(blk_get_aio_context(s->blk));
fc73548e
SH
592 blk_io_plug(s->blk);
593
9ef9d402
SH
594 do {
595 virtio_queue_set_notification(vq, 0);
596
597 while ((req = virtio_blk_get_request(s, vq))) {
07931698 598 progress = true;
9ef9d402
SH
599 if (virtio_blk_handle_request(req, &mrb)) {
600 virtqueue_detach_element(req->vq, &req->elem, 0);
601 virtio_blk_free_request(req);
602 break;
603 }
20ea686a 604 }
9ef9d402
SH
605
606 virtio_queue_set_notification(vq, 1);
607 } while (!virtio_queue_empty(vq));
91553dcc 608
95f7142a
PL
609 if (mrb.num_reqs) {
610 virtio_blk_submit_multireq(s->blk, &mrb);
611 }
fc73548e
SH
612
613 blk_io_unplug(s->blk);
9d456654 614 aio_context_release(blk_get_aio_context(s->blk));
07931698
FZ
615 return progress;
616}
617
618static void virtio_blk_handle_output_do(VirtIOBlock *s, VirtQueue *vq)
619{
620 virtio_blk_handle_vq(s, vq);
6e02c38d
AL
621}
622
8a2fad57
MT
623static void virtio_blk_handle_output(VirtIODevice *vdev, VirtQueue *vq)
624{
625 VirtIOBlock *s = (VirtIOBlock *)vdev;
626
627 if (s->dataplane) {
628 /* Some guests kick before setting VIRTIO_CONFIG_S_DRIVER_OK so start
629 * dataplane here instead of waiting for .set_status().
630 */
9ffe337c 631 virtio_device_start_ioeventfd(vdev);
8a2fad57
MT
632 if (!s->dataplane_disabled) {
633 return;
634 }
635 }
07931698 636 virtio_blk_handle_output_do(s, vq);
8a2fad57
MT
637}
638
213189ab 639static void virtio_blk_dma_restart_bh(void *opaque)
869a5c6d
AL
640{
641 VirtIOBlock *s = opaque;
642 VirtIOBlockReq *req = s->rq;
95f7142a 643 MultiReqBuffer mrb = {};
869a5c6d 644
213189ab
MA
645 qemu_bh_delete(s->bh);
646 s->bh = NULL;
869a5c6d
AL
647
648 s->rq = NULL;
649
1919631e 650 aio_context_acquire(blk_get_aio_context(s->conf.conf.blk));
869a5c6d 651 while (req) {
1bdb176a 652 VirtIOBlockReq *next = req->next;
20ea686a
GK
653 if (virtio_blk_handle_request(req, &mrb)) {
654 /* Device is now broken and won't do any processing until it gets
655 * reset. Already queued requests will be lost: let's purge them.
656 */
657 while (req) {
658 next = req->next;
659 virtqueue_detach_element(req->vq, &req->elem, 0);
660 virtio_blk_free_request(req);
661 req = next;
662 }
663 break;
664 }
1bdb176a 665 req = next;
869a5c6d 666 }
f1b52868 667
95f7142a
PL
668 if (mrb.num_reqs) {
669 virtio_blk_submit_multireq(s->blk, &mrb);
670 }
1919631e 671 aio_context_release(blk_get_aio_context(s->conf.conf.blk));
869a5c6d
AL
672}
673
1dfb4dd9
LC
674static void virtio_blk_dma_restart_cb(void *opaque, int running,
675 RunState state)
213189ab
MA
676{
677 VirtIOBlock *s = opaque;
678
392808b4 679 if (!running) {
213189ab 680 return;
392808b4 681 }
213189ab
MA
682
683 if (!s->bh) {
4be74634 684 s->bh = aio_bh_new(blk_get_aio_context(s->conf.conf.blk),
4407c1c5 685 virtio_blk_dma_restart_bh, s);
213189ab
MA
686 qemu_bh_schedule(s->bh);
687 }
688}
689
6e02c38d
AL
690static void virtio_blk_reset(VirtIODevice *vdev)
691{
1cc91b7d 692 VirtIOBlock *s = VIRTIO_BLK(vdev);
6e40b3bf 693 AioContext *ctx;
26307f6a 694 VirtIOBlockReq *req;
392808b4 695
6e40b3bf
AY
696 ctx = blk_get_aio_context(s->blk);
697 aio_context_acquire(ctx);
698 blk_drain(s->blk);
699
26307f6a
FZ
700 /* We drop queued requests after blk_drain() because blk_drain() itself can
701 * produce them. */
702 while (s->rq) {
703 req = s->rq;
704 s->rq = req->next;
97b93c8a 705 virtqueue_detach_element(req->vq, &req->elem, 0);
26307f6a
FZ
706 virtio_blk_free_request(req);
707 }
708
6e40b3bf
AY
709 aio_context_release(ctx);
710
9ffe337c 711 assert(!s->dataplane_started);
4be74634 712 blk_set_enable_write_cache(s->blk, s->original_wce);
6e02c38d
AL
713}
714
bf011293 715/* coalesce internal state, copy to pci i/o region 0
716 */
6e02c38d
AL
717static void virtio_blk_update_config(VirtIODevice *vdev, uint8_t *config)
718{
1cc91b7d 719 VirtIOBlock *s = VIRTIO_BLK(vdev);
2a30307f 720 BlockConf *conf = &s->conf.conf;
6e02c38d
AL
721 struct virtio_blk_config blkcfg;
722 uint64_t capacity;
f7516731 723 int blk_size = conf->logical_block_size;
6e02c38d 724
4be74634 725 blk_get_geometry(s->blk, &capacity);
5c5dafdc 726 memset(&blkcfg, 0, sizeof(blkcfg));
783d1897
RR
727 virtio_stq_p(vdev, &blkcfg.capacity, capacity);
728 virtio_stl_p(vdev, &blkcfg.seg_max, 128 - 2);
907eb3e5 729 virtio_stw_p(vdev, &blkcfg.geometry.cylinders, conf->cyls);
783d1897 730 virtio_stl_p(vdev, &blkcfg.blk_size, blk_size);
f7516731
MA
731 virtio_stw_p(vdev, &blkcfg.min_io_size, conf->min_io_size / blk_size);
732 virtio_stw_p(vdev, &blkcfg.opt_io_size, conf->opt_io_size / blk_size);
907eb3e5 733 blkcfg.geometry.heads = conf->heads;
136be99e
CB
734 /*
735 * We must ensure that the block device capacity is a multiple of
e03ba136 736 * the logical block size. If that is not the case, let's use
136be99e
CB
737 * sector_mask to adopt the geometry to have a correct picture.
738 * For those devices where the capacity is ok for the given geometry
e03ba136 739 * we don't touch the sector value of the geometry, since some devices
136be99e
CB
740 * (like s390 dasd) need a specific value. Here the capacity is already
741 * cyls*heads*secs*blk_size and the sector value is not block size
742 * divided by 512 - instead it is the amount of blk_size blocks
743 * per track (cylinder).
744 */
4be74634 745 if (blk_getlength(s->blk) / conf->heads / conf->secs % blk_size) {
907eb3e5 746 blkcfg.geometry.sectors = conf->secs & ~s->sector_mask;
136be99e 747 } else {
907eb3e5 748 blkcfg.geometry.sectors = conf->secs;
136be99e 749 }
c7085da7 750 blkcfg.size_max = 0;
f7516731 751 blkcfg.physical_block_exp = get_physical_block_exp(conf);
9752c371 752 blkcfg.alignment_offset = 0;
4be74634 753 blkcfg.wce = blk_enable_write_cache(s->blk);
2f270590 754 virtio_stw_p(vdev, &blkcfg.num_queues, s->conf.num_queues);
37d5ddd6 755 memcpy(config, &blkcfg, sizeof(struct virtio_blk_config));
6e02c38d
AL
756}
757
13e3dce0
PB
758static void virtio_blk_set_config(VirtIODevice *vdev, const uint8_t *config)
759{
1cc91b7d 760 VirtIOBlock *s = VIRTIO_BLK(vdev);
13e3dce0
PB
761 struct virtio_blk_config blkcfg;
762
763 memcpy(&blkcfg, config, sizeof(blkcfg));
6d7e73d6 764
4be74634
MA
765 aio_context_acquire(blk_get_aio_context(s->blk));
766 blk_set_enable_write_cache(s->blk, blkcfg.wce != 0);
767 aio_context_release(blk_get_aio_context(s->blk));
13e3dce0
PB
768}
769
9d5b731d
JW
770static uint64_t virtio_blk_get_features(VirtIODevice *vdev, uint64_t features,
771 Error **errp)
6e02c38d 772{
1cc91b7d 773 VirtIOBlock *s = VIRTIO_BLK(vdev);
1063b8b1 774
0cd09c3a
CH
775 virtio_add_feature(&features, VIRTIO_BLK_F_SEG_MAX);
776 virtio_add_feature(&features, VIRTIO_BLK_F_GEOMETRY);
777 virtio_add_feature(&features, VIRTIO_BLK_F_TOPOLOGY);
778 virtio_add_feature(&features, VIRTIO_BLK_F_BLK_SIZE);
95129d6f 779 if (virtio_has_feature(features, VIRTIO_F_VERSION_1)) {
efb8206c
JW
780 if (s->conf.scsi) {
781 error_setg(errp, "Please set scsi=off for virtio-blk devices in order to use virtio 1.0");
782 return 0;
783 }
efb8206c 784 } else {
c9b11f97 785 virtio_clear_feature(&features, VIRTIO_F_ANY_LAYOUT);
efb8206c
JW
786 virtio_add_feature(&features, VIRTIO_BLK_F_SCSI);
787 }
aa659be3 788
2a30307f 789 if (s->conf.config_wce) {
0cd09c3a 790 virtio_add_feature(&features, VIRTIO_BLK_F_CONFIG_WCE);
8a873ba7 791 }
4be74634 792 if (blk_enable_write_cache(s->blk)) {
0cd09c3a 793 virtio_add_feature(&features, VIRTIO_BLK_F_WCE);
4be74634
MA
794 }
795 if (blk_is_read_only(s->blk)) {
0cd09c3a 796 virtio_add_feature(&features, VIRTIO_BLK_F_RO);
4be74634 797 }
2f270590
SH
798 if (s->conf.num_queues > 1) {
799 virtio_add_feature(&features, VIRTIO_BLK_F_MQ);
800 }
1063b8b1
CH
801
802 return features;
6e02c38d
AL
803}
804
9315cbfd
PB
805static void virtio_blk_set_status(VirtIODevice *vdev, uint8_t status)
806{
1cc91b7d 807 VirtIOBlock *s = VIRTIO_BLK(vdev);
9315cbfd 808
9ffe337c
PB
809 if (!(status & (VIRTIO_CONFIG_S_DRIVER | VIRTIO_CONFIG_S_DRIVER_OK))) {
810 assert(!s->dataplane_started);
392808b4 811 }
392808b4 812
9315cbfd
PB
813 if (!(status & VIRTIO_CONFIG_S_DRIVER_OK)) {
814 return;
815 }
816
ef5bc962
PB
817 /* A guest that supports VIRTIO_BLK_F_CONFIG_WCE must be able to send
818 * cache flushes. Thus, the "auto writethrough" behavior is never
819 * necessary for guests that support the VIRTIO_BLK_F_CONFIG_WCE feature.
820 * Leaving it enabled would break the following sequence:
821 *
822 * Guest started with "-drive cache=writethrough"
823 * Guest sets status to 0
824 * Guest sets DRIVER bit in status field
825 * Guest reads host features (WCE=0, CONFIG_WCE=1)
826 * Guest writes guest features (WCE=0, CONFIG_WCE=1)
827 * Guest writes 1 to the WCE configuration field (writeback mode)
828 * Guest sets DRIVER_OK bit in status field
829 *
4be74634 830 * s->blk would erroneously be placed in writethrough mode.
ef5bc962 831 */
95129d6f 832 if (!virtio_vdev_has_feature(vdev, VIRTIO_BLK_F_CONFIG_WCE)) {
4be74634
MA
833 aio_context_acquire(blk_get_aio_context(s->blk));
834 blk_set_enable_write_cache(s->blk,
95129d6f
CH
835 virtio_vdev_has_feature(vdev,
836 VIRTIO_BLK_F_WCE));
4be74634 837 aio_context_release(blk_get_aio_context(s->blk));
ef5bc962 838 }
9315cbfd
PB
839}
840
b2b295a7
GK
841static void virtio_blk_save_device(VirtIODevice *vdev, QEMUFile *f)
842{
843 VirtIOBlock *s = VIRTIO_BLK(vdev);
844 VirtIOBlockReq *req = s->rq;
845
869a5c6d
AL
846 while (req) {
847 qemu_put_sbyte(f, 1);
30d8bf6d
SH
848
849 if (s->conf.num_queues > 1) {
850 qemu_put_be32(f, virtio_get_queue_index(req->vq));
851 }
852
ab281c17 853 qemu_put_virtqueue_element(f, &req->elem);
869a5c6d
AL
854 req = req->next;
855 }
856 qemu_put_sbyte(f, 0);
6e02c38d
AL
857}
858
b2b295a7
GK
859static int virtio_blk_load_device(VirtIODevice *vdev, QEMUFile *f,
860 int version_id)
861{
862 VirtIOBlock *s = VIRTIO_BLK(vdev);
2a633c46 863
869a5c6d 864 while (qemu_get_sbyte(f)) {
30d8bf6d
SH
865 unsigned nvqs = s->conf.num_queues;
866 unsigned vq_idx = 0;
ab281c17 867 VirtIOBlockReq *req;
30d8bf6d
SH
868
869 if (nvqs > 1) {
870 vq_idx = qemu_get_be32(f);
871
872 if (vq_idx >= nvqs) {
873 error_report("Invalid virtqueue index in request list: %#x",
874 vq_idx);
875 return -EINVAL;
876 }
877 }
878
8607f5c3 879 req = qemu_get_virtqueue_element(vdev, f, sizeof(VirtIOBlockReq));
30d8bf6d 880 virtio_blk_init_request(s, virtio_get_queue(vdev, vq_idx), req);
869a5c6d 881 req->next = s->rq;
20a81e4d 882 s->rq = req;
869a5c6d 883 }
6e02c38d
AL
884
885 return 0;
886}
887
145feb17 888static void virtio_blk_resize(void *opaque)
e5051fc7 889{
1cc91b7d 890 VirtIODevice *vdev = VIRTIO_DEVICE(opaque);
e5051fc7 891
1cc91b7d 892 virtio_notify_config(vdev);
e5051fc7
CH
893}
894
0e49de52 895static const BlockDevOps virtio_block_ops = {
145feb17 896 .resize_cb = virtio_blk_resize,
0e49de52
MA
897};
898
75884afd 899static void virtio_blk_device_realize(DeviceState *dev, Error **errp)
1c028ddf 900{
75884afd 901 VirtIODevice *vdev = VIRTIO_DEVICE(dev);
179b417e 902 VirtIOBlock *s = VIRTIO_BLK(dev);
2a30307f 903 VirtIOBlkConf *conf = &s->conf;
3ffeeef7 904 Error *err = NULL;
2f270590 905 unsigned i;
cf21e106 906
4be74634 907 if (!conf->conf.blk) {
75884afd
AF
908 error_setg(errp, "drive property not set");
909 return;
d75d25e3 910 }
4be74634 911 if (!blk_is_inserted(conf->conf.blk)) {
75884afd
AF
912 error_setg(errp, "Device needs media, but drive is empty");
913 return;
98f28ad7 914 }
2f270590
SH
915 if (!conf->num_queues) {
916 error_setg(errp, "num-queues property must be larger than 0");
917 return;
918 }
d75d25e3 919
2a30307f 920 blkconf_serial(&conf->conf, &conf->serial);
f6166a06 921 blkconf_apply_backend_options(&conf->conf);
4be74634 922 s->original_wce = blk_enable_write_cache(conf->conf.blk);
2a30307f 923 blkconf_geometry(&conf->conf, NULL, 65535, 255, 255, &err);
5ff5efb4
FZ
924 if (err) {
925 error_propagate(errp, err);
75884afd 926 return;
b7eb0c9f 927 }
0eb28a42 928 blkconf_blocksizes(&conf->conf);
a8686a9b 929
05ff6865
FK
930 virtio_init(vdev, "virtio-blk", VIRTIO_ID_BLOCK,
931 sizeof(struct virtio_blk_config));
6e02c38d 932
4be74634 933 s->blk = conf->conf.blk;
869a5c6d 934 s->rq = NULL;
2a30307f 935 s->sector_mask = (s->conf.conf.logical_block_size / BDRV_SECTOR_SIZE) - 1;
e63e7fde 936
2f270590 937 for (i = 0; i < conf->num_queues; i++) {
9ffe337c 938 virtio_add_queue(vdev, 128, virtio_blk_handle_output);
2f270590 939 }
2a30307f 940 virtio_blk_data_plane_create(vdev, conf, &s->dataplane, &err);
3ffeeef7 941 if (err != NULL) {
75884afd 942 error_propagate(errp, err);
6a1a8cc7 943 virtio_cleanup(vdev);
75884afd 944 return;
392808b4 945 }
6e02c38d 946
69b302b2 947 s->change = qemu_add_vm_change_state_handler(virtio_blk_dma_restart_cb, s);
4be74634
MA
948 blk_set_dev_ops(s->blk, &virtio_block_ops, s);
949 blk_set_guest_block_size(s->blk, s->conf.conf.logical_block_size);
6e02c38d 950
4be74634 951 blk_iostatus_enable(s->blk);
1c028ddf
FK
952}
953
306ec6c3 954static void virtio_blk_device_unrealize(DeviceState *dev, Error **errp)
1c028ddf 955{
306ec6c3
AF
956 VirtIODevice *vdev = VIRTIO_DEVICE(dev);
957 VirtIOBlock *s = VIRTIO_BLK(dev);
958
1c028ddf
FK
959 virtio_blk_data_plane_destroy(s->dataplane);
960 s->dataplane = NULL;
1c028ddf 961 qemu_del_vm_change_state_handler(s->change);
4be74634 962 blockdev_mark_auto_del(s->blk);
6a1a8cc7 963 virtio_cleanup(vdev);
1c028ddf
FK
964}
965
467b3f33
SH
966static void virtio_blk_instance_init(Object *obj)
967{
968 VirtIOBlock *s = VIRTIO_BLK(obj);
969
970 object_property_add_link(obj, "iothread", TYPE_IOTHREAD,
2a30307f 971 (Object **)&s->conf.iothread,
467b3f33
SH
972 qdev_prop_allow_set_link_before_realize,
973 OBJ_PROP_LINK_UNREF_ON_RELEASE, NULL);
2a30307f 974 device_add_bootindex_property(obj, &s->conf.conf.bootindex,
3342ec32
GA
975 "bootindex", "/disk@0,0",
976 DEVICE(obj), NULL);
467b3f33
SH
977}
978
977a117f
HP
979static const VMStateDescription vmstate_virtio_blk = {
980 .name = "virtio-blk",
981 .minimum_version_id = 2,
982 .version_id = 2,
983 .fields = (VMStateField[]) {
984 VMSTATE_VIRTIO_DEVICE,
985 VMSTATE_END_OF_LIST()
986 },
987};
bbded32c 988
1c028ddf 989static Property virtio_blk_properties[] = {
2a30307f 990 DEFINE_BLOCK_PROPERTIES(VirtIOBlock, conf.conf),
8c398252 991 DEFINE_BLOCK_ERROR_PROPERTIES(VirtIOBlock, conf.conf),
2a30307f
MA
992 DEFINE_BLOCK_CHS_PROPERTIES(VirtIOBlock, conf.conf),
993 DEFINE_PROP_STRING("serial", VirtIOBlock, conf.serial),
994 DEFINE_PROP_BIT("config-wce", VirtIOBlock, conf.config_wce, 0, true),
32a877e4 995#ifdef __linux__
ed65fd1a 996 DEFINE_PROP_BIT("scsi", VirtIOBlock, conf.scsi, 0, false),
32a877e4 997#endif
c99495ac
PL
998 DEFINE_PROP_BIT("request-merging", VirtIOBlock, conf.request_merging, 0,
999 true),
2f270590 1000 DEFINE_PROP_UINT16("num-queues", VirtIOBlock, conf.num_queues, 1),
1c028ddf
FK
1001 DEFINE_PROP_END_OF_LIST(),
1002};
1003
1004static void virtio_blk_class_init(ObjectClass *klass, void *data)
1005{
1006 DeviceClass *dc = DEVICE_CLASS(klass);
1007 VirtioDeviceClass *vdc = VIRTIO_DEVICE_CLASS(klass);
75884afd 1008
1c028ddf 1009 dc->props = virtio_blk_properties;
bbded32c 1010 dc->vmsd = &vmstate_virtio_blk;
125ee0ed 1011 set_bit(DEVICE_CATEGORY_STORAGE, dc->categories);
75884afd 1012 vdc->realize = virtio_blk_device_realize;
306ec6c3 1013 vdc->unrealize = virtio_blk_device_unrealize;
1c028ddf
FK
1014 vdc->get_config = virtio_blk_update_config;
1015 vdc->set_config = virtio_blk_set_config;
1016 vdc->get_features = virtio_blk_get_features;
1017 vdc->set_status = virtio_blk_set_status;
1018 vdc->reset = virtio_blk_reset;
b2b295a7
GK
1019 vdc->save = virtio_blk_save_device;
1020 vdc->load = virtio_blk_load_device;
9ffe337c
PB
1021 vdc->start_ioeventfd = virtio_blk_data_plane_start;
1022 vdc->stop_ioeventfd = virtio_blk_data_plane_stop;
1c028ddf
FK
1023}
1024
b5c7ceaf 1025static const TypeInfo virtio_blk_info = {
1c028ddf
FK
1026 .name = TYPE_VIRTIO_BLK,
1027 .parent = TYPE_VIRTIO_DEVICE,
1028 .instance_size = sizeof(VirtIOBlock),
467b3f33 1029 .instance_init = virtio_blk_instance_init,
1c028ddf
FK
1030 .class_init = virtio_blk_class_init,
1031};
1032
1033static void virtio_register_types(void)
1034{
b5c7ceaf 1035 type_register_static(&virtio_blk_info);
1c028ddf
FK
1036}
1037
1038type_init(virtio_register_types)