Merge remote-tracking branch 'origin/master' into staging
[qemu/kevin.git] / block_int.h
blob0e5a032e775f08c538ccffa11186b1b42cfca83f
1 /*
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
22 * THE SOFTWARE.
24 #ifndef BLOCK_INT_H
25 #define BLOCK_INT_H
27 #include "block.h"
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 {
57 int64_t bps[3];
58 int64_t iops[3];
59 } BlockIOLimit;
61 typedef struct BlockIOBaseValue {
62 uint64_t bytes[2];
63 uint64_t ios[2];
64 } BlockIOBaseValue;
66 typedef struct BlockJob BlockJob;
68 /**
69 * BlockJobType:
71 * A class type for block job objects.
73 typedef struct BlockJobType {
74 /** Derived BlockJob struct size */
75 size_t instance_size;
77 /** String describing the operation, part of query-block-jobs QMP API */
78 const char *job_type;
80 /** Optional callback for job types that support setting a speed limit */
81 int (*set_speed)(BlockJob *job, int64_t value);
82 } BlockJobType;
84 /**
85 * BlockJob:
87 * Long-running operation on a BlockDriverState.
89 struct BlockJob {
90 /** The job type, including the job vtable. */
91 const BlockJobType *job_type;
93 /** The block device on which the job is operating. */
94 BlockDriverState *bs;
96 /**
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
101 * block device.
103 bool cancelled;
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.
112 bool busy;
114 /** Offset that is published by the query-block-jobs QMP API */
115 int64_t offset;
117 /** Length that is published by the query-block-jobs QMP API */
118 int64_t len;
120 /** Speed that was set with @block_job_set_speed. */
121 int64_t 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. */
127 void *opaque;
130 struct BlockDriver {
131 const char *format_name;
132 int instance_size;
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);
145 /* aio */
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
166 * instead.
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
189 * process.
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
256 * copied as well.
258 struct BlockDriverState {
259 int64_t total_sectors; /* if we are reading a disk image, give its
260 size in sectors */
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 */
271 void *opaque;
273 void *dev; /* attached device model, if any */
274 /* TODO change to DeviceState when all users are qdevified */
275 const BlockDevOps *dev_ops;
276 void *dev_opaque;
278 char filename[1024];
279 char backing_file[1024]; /* if non zero, the image is a diff of
280 this file image */
281 char backing_format[16]; /* if non-zero and backing_file exists */
282 int is_temporary;
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 */
291 int64_t slice_time;
292 int64_t slice_start;
293 int64_t slice_end;
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 */
307 int growable;
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;
323 int64_t dirty_count;
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 */
330 BlockJob *job;
333 void get_tmp_filename(char *filename, int size);
335 void bdrv_set_io_limits(BlockDriverState *bs,
336 BlockIOLimit *io_limits);
338 #ifdef _WIN32
339 int is_windows_drive(const char *filename);
340 #endif
343 * block_job_create:
344 * @job_type: The class object for the newly-created job.
345 * @bs: The block
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
353 * completed.
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
367 * free @job.
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);
382 * block_job_cancel:
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);
398 * block_job_cancel:
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);
411 * stream_start:
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,
428 void *opaque);
430 #endif /* BLOCK_INT_H */