2 * QEMU System Emulator block driver
4 * Copyright (c) 2003 Fabrice Bellard
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
28 #include "qemu-option.h"
29 #include "qemu-queue.h"
30 #include "qemu-coroutine.h"
31 #include "qemu-timer.h"
32 #include "qapi-types.h"
34 #define BLOCK_FLAG_ENCRYPT 1
35 #define BLOCK_FLAG_COMPAT6 4
37 #define BLOCK_IO_LIMIT_READ 0
38 #define BLOCK_IO_LIMIT_WRITE 1
39 #define BLOCK_IO_LIMIT_TOTAL 2
41 #define BLOCK_IO_SLICE_TIME 100000000
42 #define NANOSECONDS_PER_SECOND 1000000000.0
44 #define BLOCK_OPT_SIZE "size"
45 #define BLOCK_OPT_ENCRYPT "encryption"
46 #define BLOCK_OPT_COMPAT6 "compat6"
47 #define BLOCK_OPT_BACKING_FILE "backing_file"
48 #define BLOCK_OPT_BACKING_FMT "backing_fmt"
49 #define BLOCK_OPT_CLUSTER_SIZE "cluster_size"
50 #define BLOCK_OPT_TABLE_SIZE "table_size"
51 #define BLOCK_OPT_PREALLOC "preallocation"
52 #define BLOCK_OPT_SUBFMT "subformat"
54 typedef struct BdrvTrackedRequest BdrvTrackedRequest
;
56 typedef struct BlockIOLimit
{
61 typedef struct BlockIOBaseValue
{
66 typedef struct BlockJob BlockJob
;
71 * A class type for block job objects.
73 typedef struct BlockJobType
{
74 /** Derived BlockJob struct size */
77 /** String describing the operation, part of query-block-jobs QMP API */
80 /** Optional callback for job types that support setting a speed limit */
81 int (*set_speed
)(BlockJob
*job
, int64_t value
);
87 * Long-running operation on a BlockDriverState.
90 /** The job type, including the job vtable. */
91 const BlockJobType
*job_type
;
93 /** The block device on which the job is operating. */
97 * Set to true if the job should cancel itself. The flag must
98 * always be tested just before toggling the busy flag from false
99 * to true. After a job has detected that the cancelled flag is
100 * true, it should not anymore issue any I/O operation to the
106 * Set to false by the job while it is in a quiescent state, where
107 * no I/O is pending and cancellation can be processed without
108 * issuing new I/O. The busy flag must be set to false when the
109 * job goes to sleep on any condition that is not detected by
110 * #qemu_aio_wait, such as a timer.
114 /** Offset that is published by the query-block-jobs QMP API */
117 /** Length that is published by the query-block-jobs QMP API */
120 /** Speed that was set with @block_job_set_speed. */
123 /** The completion function that will be called when the job completes. */
124 BlockDriverCompletionFunc
*cb
;
126 /** The opaque value that is passed to the completion function. */
131 const char *format_name
;
133 int (*bdrv_probe
)(const uint8_t *buf
, int buf_size
, const char *filename
);
134 int (*bdrv_probe_device
)(const char *filename
);
135 int (*bdrv_open
)(BlockDriverState
*bs
, int flags
);
136 int (*bdrv_file_open
)(BlockDriverState
*bs
, const char *filename
, int flags
);
137 int (*bdrv_read
)(BlockDriverState
*bs
, int64_t sector_num
,
138 uint8_t *buf
, int nb_sectors
);
139 int (*bdrv_write
)(BlockDriverState
*bs
, int64_t sector_num
,
140 const uint8_t *buf
, int nb_sectors
);
141 void (*bdrv_close
)(BlockDriverState
*bs
);
142 int (*bdrv_create
)(const char *filename
, QEMUOptionParameter
*options
);
143 int (*bdrv_set_key
)(BlockDriverState
*bs
, const char *key
);
144 int (*bdrv_make_empty
)(BlockDriverState
*bs
);
146 BlockDriverAIOCB
*(*bdrv_aio_readv
)(BlockDriverState
*bs
,
147 int64_t sector_num
, QEMUIOVector
*qiov
, int nb_sectors
,
148 BlockDriverCompletionFunc
*cb
, void *opaque
);
149 BlockDriverAIOCB
*(*bdrv_aio_writev
)(BlockDriverState
*bs
,
150 int64_t sector_num
, QEMUIOVector
*qiov
, int nb_sectors
,
151 BlockDriverCompletionFunc
*cb
, void *opaque
);
152 BlockDriverAIOCB
*(*bdrv_aio_flush
)(BlockDriverState
*bs
,
153 BlockDriverCompletionFunc
*cb
, void *opaque
);
154 BlockDriverAIOCB
*(*bdrv_aio_discard
)(BlockDriverState
*bs
,
155 int64_t sector_num
, int nb_sectors
,
156 BlockDriverCompletionFunc
*cb
, void *opaque
);
158 int coroutine_fn (*bdrv_co_readv
)(BlockDriverState
*bs
,
159 int64_t sector_num
, int nb_sectors
, QEMUIOVector
*qiov
);
160 int coroutine_fn (*bdrv_co_writev
)(BlockDriverState
*bs
,
161 int64_t sector_num
, int nb_sectors
, QEMUIOVector
*qiov
);
163 * Efficiently zero a region of the disk image. Typically an image format
164 * would use a compact metadata representation to implement this. This
165 * function pointer may be NULL and .bdrv_co_writev() will be called
168 int coroutine_fn (*bdrv_co_write_zeroes
)(BlockDriverState
*bs
,
169 int64_t sector_num
, int nb_sectors
);
170 int coroutine_fn (*bdrv_co_discard
)(BlockDriverState
*bs
,
171 int64_t sector_num
, int nb_sectors
);
172 int coroutine_fn (*bdrv_co_is_allocated
)(BlockDriverState
*bs
,
173 int64_t sector_num
, int nb_sectors
, int *pnum
);
176 * Invalidate any cached meta-data.
178 void (*bdrv_invalidate_cache
)(BlockDriverState
*bs
);
181 * Flushes all data that was already written to the OS all the way down to
182 * the disk (for example raw-posix calls fsync()).
184 int coroutine_fn (*bdrv_co_flush_to_disk
)(BlockDriverState
*bs
);
187 * Flushes all internal caches to the OS. The data may still sit in a
188 * writeback cache of the host OS, but it will survive a crash of the qemu
191 int coroutine_fn (*bdrv_co_flush_to_os
)(BlockDriverState
*bs
);
193 const char *protocol_name
;
194 int (*bdrv_truncate
)(BlockDriverState
*bs
, int64_t offset
);
195 int64_t (*bdrv_getlength
)(BlockDriverState
*bs
);
196 int64_t (*bdrv_get_allocated_file_size
)(BlockDriverState
*bs
);
197 int (*bdrv_write_compressed
)(BlockDriverState
*bs
, int64_t sector_num
,
198 const uint8_t *buf
, int nb_sectors
);
200 int (*bdrv_snapshot_create
)(BlockDriverState
*bs
,
201 QEMUSnapshotInfo
*sn_info
);
202 int (*bdrv_snapshot_goto
)(BlockDriverState
*bs
,
203 const char *snapshot_id
);
204 int (*bdrv_snapshot_delete
)(BlockDriverState
*bs
, const char *snapshot_id
);
205 int (*bdrv_snapshot_list
)(BlockDriverState
*bs
,
206 QEMUSnapshotInfo
**psn_info
);
207 int (*bdrv_snapshot_load_tmp
)(BlockDriverState
*bs
,
208 const char *snapshot_name
);
209 int (*bdrv_get_info
)(BlockDriverState
*bs
, BlockDriverInfo
*bdi
);
211 int (*bdrv_save_vmstate
)(BlockDriverState
*bs
, const uint8_t *buf
,
212 int64_t pos
, int size
);
213 int (*bdrv_load_vmstate
)(BlockDriverState
*bs
, uint8_t *buf
,
214 int64_t pos
, int size
);
216 int (*bdrv_change_backing_file
)(BlockDriverState
*bs
,
217 const char *backing_file
, const char *backing_fmt
);
219 /* removable device specific */
220 int (*bdrv_is_inserted
)(BlockDriverState
*bs
);
221 int (*bdrv_media_changed
)(BlockDriverState
*bs
);
222 void (*bdrv_eject
)(BlockDriverState
*bs
, bool eject_flag
);
223 void (*bdrv_lock_medium
)(BlockDriverState
*bs
, bool locked
);
225 /* to control generic scsi devices */
226 int (*bdrv_ioctl
)(BlockDriverState
*bs
, unsigned long int req
, void *buf
);
227 BlockDriverAIOCB
*(*bdrv_aio_ioctl
)(BlockDriverState
*bs
,
228 unsigned long int req
, void *buf
,
229 BlockDriverCompletionFunc
*cb
, void *opaque
);
231 /* List of options for creating images, terminated by name == NULL */
232 QEMUOptionParameter
*create_options
;
236 * Returns 0 for completed check, -errno for internal errors.
237 * The check results are stored in result.
239 int (*bdrv_check
)(BlockDriverState
* bs
, BdrvCheckResult
*result
);
241 void (*bdrv_debug_event
)(BlockDriverState
*bs
, BlkDebugEvent event
);
244 * Returns 1 if newly created images are guaranteed to contain only
245 * zeros, 0 otherwise.
247 int (*bdrv_has_zero_init
)(BlockDriverState
*bs
);
249 QLIST_ENTRY(BlockDriver
) list
;
253 * Note: the function bdrv_append() copies and swaps contents of
254 * BlockDriverStates, so if you add new fields to this struct, please
255 * inspect bdrv_append() to determine if the new fields need to be
258 struct BlockDriverState
{
259 int64_t total_sectors
; /* if we are reading a disk image, give its
261 int read_only
; /* if true, the media is read only */
262 int keep_read_only
; /* if true, the media was requested to stay read only */
263 int open_flags
; /* flags used to open the file, re-used for re-open */
264 int encrypted
; /* if true, the media is encrypted */
265 int valid_key
; /* if true, a valid encryption key has been set */
266 int sg
; /* if true, the device is a /dev/sg* */
267 int copy_on_read
; /* if true, copy read backing sectors into image
268 note this is a reference count */
270 BlockDriver
*drv
; /* NULL means no media */
273 void *dev
; /* attached device model, if any */
274 /* TODO change to DeviceState when all users are qdevified */
275 const BlockDevOps
*dev_ops
;
279 char backing_file
[1024]; /* if non zero, the image is a diff of
281 char backing_format
[16]; /* if non-zero and backing_file exists */
284 BlockDriverState
*backing_hd
;
285 BlockDriverState
*file
;
287 /* number of in-flight copy-on-read requests */
288 unsigned int copy_on_read_in_flight
;
290 /* the time for latest disk I/O */
294 BlockIOLimit io_limits
;
295 BlockIOBaseValue io_base
;
296 CoQueue throttled_reqs
;
297 QEMUTimer
*block_timer
;
298 bool io_limits_enabled
;
300 /* I/O stats (display with "info blockstats"). */
301 uint64_t nr_bytes
[BDRV_MAX_IOTYPE
];
302 uint64_t nr_ops
[BDRV_MAX_IOTYPE
];
303 uint64_t total_time_ns
[BDRV_MAX_IOTYPE
];
304 uint64_t wr_highest_sector
;
306 /* Whether the disk can expand beyond total_sectors */
309 /* the memory alignment required for the buffers handled by this driver */
310 int buffer_alignment
;
312 /* do we need to tell the quest if we have a volatile write cache? */
313 int enable_write_cache
;
315 /* NOTE: the following infos are only hints for real hardware
316 drivers. They are not used by the block driver */
317 int cyls
, heads
, secs
, translation
;
318 BlockErrorAction on_read_error
, on_write_error
;
319 bool iostatus_enabled
;
320 BlockDeviceIoStatus iostatus
;
321 char device_name
[32];
322 unsigned long *dirty_bitmap
;
324 int in_use
; /* users other than guest access, eg. block migration */
325 QTAILQ_ENTRY(BlockDriverState
) list
;
327 QLIST_HEAD(, BdrvTrackedRequest
) tracked_requests
;
329 /* long-running background operation */
333 void get_tmp_filename(char *filename
, int size
);
335 void bdrv_set_io_limits(BlockDriverState
*bs
,
336 BlockIOLimit
*io_limits
);
339 int is_windows_drive(const char *filename
);
344 * @job_type: The class object for the newly-created job.
346 * @cb: Completion function for the job.
347 * @opaque: Opaque pointer value passed to @cb.
349 * Create a new long-running block device job and return it. The job
350 * will call @cb asynchronously when the job completes. Note that
351 * @bs may have been closed at the time the @cb it is called. If
352 * this is the case, the job may be reported as either cancelled or
355 * This function is not part of the public job interface; it should be
356 * called from a wrapper that is specific to the job type.
358 void *block_job_create(const BlockJobType
*job_type
, BlockDriverState
*bs
,
359 BlockDriverCompletionFunc
*cb
, void *opaque
);
362 * block_job_complete:
363 * @job: The job being completed.
364 * @ret: The status code.
366 * Call the completion function that was registered at creation time, and
369 void block_job_complete(BlockJob
*job
, int ret
);
372 * block_job_set_speed:
373 * @job: The job to set the speed for.
374 * @speed: The new value
376 * Set a rate-limiting parameter for the job; the actual meaning may
377 * vary depending on the job type.
379 int block_job_set_speed(BlockJob
*job
, int64_t value
);
383 * @job: The job to be canceled.
385 * Asynchronously cancel the specified job.
387 void block_job_cancel(BlockJob
*job
);
390 * block_job_is_cancelled:
391 * @job: The job being queried.
393 * Returns whether the job is scheduled for cancellation.
395 bool block_job_is_cancelled(BlockJob
*job
);
399 * @job: The job to be canceled.
401 * Asynchronously cancel the job and wait for it to reach a quiescent
402 * state. Note that the completion callback will still be called
403 * asynchronously, hence it is *not* valid to call #bdrv_delete
404 * immediately after #block_job_cancel_sync. Users of block jobs
405 * will usually protect the BlockDriverState objects with a reference
406 * count, should this be a concern.
408 void block_job_cancel_sync(BlockJob
*job
);
412 * @bs: Block device to operate on.
413 * @base: Block device that will become the new base, or %NULL to
414 * flatten the whole backing file chain onto @bs.
415 * @base_id: The file name that will be written to @bs as the new
416 * backing file if the job completes. Ignored if @base is %NULL.
417 * @cb: Completion function for the job.
418 * @opaque: Opaque pointer value passed to @cb.
420 * Start a streaming operation on @bs. Clusters that are unallocated
421 * in @bs, but allocated in any image between @base and @bs (both
422 * exclusive) will be written to @bs. At the end of a successful
423 * streaming job, the backing file of @bs will be changed to
424 * @base_id in the written image and to @base in the live BlockDriverState.
426 int stream_start(BlockDriverState
*bs
, BlockDriverState
*base
,
427 const char *base_id
, BlockDriverCompletionFunc
*cb
,
430 #endif /* BLOCK_INT_H */