LXR qemu/include/block/blockjob.h

   1/*
   2 * Declarations for long-running block device operations
   3 *
   4 * Copyright (c) 2011 IBM Corp.
   5 * Copyright (c) 2012 Red Hat, Inc.
   6 *
   7 * Permission is hereby granted, free of charge, to any person obtaining a copy
   8 * of this software and associated documentation files (the "Software"), to deal
   9 * in the Software without restriction, including without limitation the rights
  10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11 * copies of the Software, and to permit persons to whom the Software is
  12 * furnished to do so, subject to the following conditions:
  13 *
  14 * The above copyright notice and this permission notice shall be included in
  15 * all copies or substantial portions of the Software.
  16 *
  17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  20 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  23 * THE SOFTWARE.
  24 */
  25
  26#ifndef BLOCKJOB_H
  27#define BLOCKJOB_H
  28
  29#include "qemu/job.h"
  30#include "block/block.h"
  31#include "qemu/ratelimit.h"
  32
  33#define BLOCK_JOB_SLICE_TIME 100000000ULL /* ns */
  34
  35typedef struct BlockJobDriver BlockJobDriver;
  36
  37/**
  38 * BlockJob:
  39 *
  40 * Long-running operation on a BlockDriverState.
  41 */
  42typedef struct BlockJob {
  43    /** Data belonging to the generic Job infrastructure */
  44    Job job;
  45
  46    /** The block device on which the job is operating.  */
  47    BlockBackend *blk;
  48
  49    /** Status that is published by the query-block-jobs QMP API */
  50    BlockDeviceIoStatus iostatus;
  51
  52    /** Speed that was set with @block_job_set_speed.  */
  53    int64_t speed;
  54
  55    /** Rate limiting data structure for implementing @speed. */
  56    RateLimit limit;
  57
  58    /** Block other operations when block job is running */
  59    Error *blocker;
  60
  61    /** Called when a cancelled job is finalised. */
  62    Notifier finalize_cancelled_notifier;
  63
  64    /** Called when a successfully completed job is finalised. */
  65    Notifier finalize_completed_notifier;
  66
  67    /** Called when the job transitions to PENDING */
  68    Notifier pending_notifier;
  69
  70    /** Called when the job transitions to READY */
  71    Notifier ready_notifier;
  72
  73    /** Called when the job coroutine yields or terminates */
  74    Notifier idle_notifier;
  75
  76    /** BlockDriverStates that are involved in this block job */
  77    GSList *nodes;
  78} BlockJob;
  79
  80/**
  81 * block_job_next:
  82 * @job: A block job, or %NULL.
  83 *
  84 * Get the next element from the list of block jobs after @job, or the
  85 * first one if @job is %NULL.
  86 *
  87 * Returns the requested job, or %NULL if there are no more jobs left.
  88 */
  89BlockJob *block_job_next(BlockJob *job);
  90
  91/**
  92 * block_job_get:
  93 * @id: The id of the block job.
  94 *
  95 * Get the block job identified by @id (which must not be %NULL).
  96 *
  97 * Returns the requested job, or %NULL if it doesn't exist.
  98 */
  99BlockJob *block_job_get(const char *id);
 100
 101/**
 102 * block_job_add_bdrv:
 103 * @job: A block job
 104 * @name: The name to assign to the new BdrvChild
 105 * @bs: A BlockDriverState that is involved in @job
 106 * @perm, @shared_perm: Permissions to request on the node
 107 *
 108 * Add @bs to the list of BlockDriverState that are involved in
 109 * @job. This means that all operations will be blocked on @bs while
 110 * @job exists.
 111 */
 112int block_job_add_bdrv(BlockJob *job, const char *name, BlockDriverState *bs,
 113                       uint64_t perm, uint64_t shared_perm, Error **errp);
 114
 115/**
 116 * block_job_remove_all_bdrv:
 117 * @job: The block job
 118 *
 119 * Remove all BlockDriverStates from the list of nodes that are involved in the
 120 * job. This removes the blockers added with block_job_add_bdrv().
 121 */
 122void block_job_remove_all_bdrv(BlockJob *job);
 123
 124/**
 125 * block_job_has_bdrv:
 126 * @job: The block job
 127 *
 128 * Searches for @bs in the list of nodes that are involved in the
 129 * job.
 130 */
 131bool block_job_has_bdrv(BlockJob *job, BlockDriverState *bs);
 132
 133/**
 134 * block_job_set_speed:
 135 * @job: The job to set the speed for.
 136 * @speed: The new value
 137 * @errp: Error object.
 138 *
 139 * Set a rate-limiting parameter for the job; the actual meaning may
 140 * vary depending on the job type.
 141 */
 142void block_job_set_speed(BlockJob *job, int64_t speed, Error **errp);
 143
 144/**
 145 * block_job_query:
 146 * @job: The job to get information about.
 147 *
 148 * Return information about a job.
 149 */
 150BlockJobInfo *block_job_query(BlockJob *job, Error **errp);
 151
 152/**
 153 * block_job_iostatus_reset:
 154 * @job: The job whose I/O status should be reset.
 155 *
 156 * Reset I/O status on @job and on BlockDriverState objects it uses,
 157 * other than job->blk.
 158 */
 159void block_job_iostatus_reset(BlockJob *job);
 160
 161/**
 162 * block_job_is_internal:
 163 * @job: The job to determine if it is user-visible or not.
 164 *
 165 * Returns true if the job should not be visible to the management layer.
 166 */
 167bool block_job_is_internal(BlockJob *job);
 168
 169/**
 170 * block_job_driver:
 171 *
 172 * Returns the driver associated with a block job.
 173 */
 174const BlockJobDriver *block_job_driver(BlockJob *job);
 175
 176#endif
 177