843e19887f64dde75055cf8842fc4db2171eff45johnlev/******************************************************************************
843e19887f64dde75055cf8842fc4db2171eff45johnlev * Unified block-device I/O interface for Xen guest OSes.
843e19887f64dde75055cf8842fc4db2171eff45johnlev * Permission is hereby granted, free of charge, to any person obtaining a copy
843e19887f64dde75055cf8842fc4db2171eff45johnlev * of this software and associated documentation files (the "Software"), to
843e19887f64dde75055cf8842fc4db2171eff45johnlev * deal in the Software without restriction, including without limitation the
843e19887f64dde75055cf8842fc4db2171eff45johnlev * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
843e19887f64dde75055cf8842fc4db2171eff45johnlev * sell copies of the Software, and to permit persons to whom the Software is
843e19887f64dde75055cf8842fc4db2171eff45johnlev * furnished to do so, subject to the following conditions:
843e19887f64dde75055cf8842fc4db2171eff45johnlev * The above copyright notice and this permission notice shall be included in
843e19887f64dde75055cf8842fc4db2171eff45johnlev * all copies or substantial portions of the Software.
843e19887f64dde75055cf8842fc4db2171eff45johnlev * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
843e19887f64dde75055cf8842fc4db2171eff45johnlev * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
843e19887f64dde75055cf8842fc4db2171eff45johnlev * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
843e19887f64dde75055cf8842fc4db2171eff45johnlev * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
843e19887f64dde75055cf8842fc4db2171eff45johnlev * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
843e19887f64dde75055cf8842fc4db2171eff45johnlev * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
843e19887f64dde75055cf8842fc4db2171eff45johnlev * DEALINGS IN THE SOFTWARE.
843e19887f64dde75055cf8842fc4db2171eff45johnlev * Copyright (c) 2003-2004, Keir Fraser
843e19887f64dde75055cf8842fc4db2171eff45johnlev * Front->back notifications: When enqueuing a new request, sending a
843e19887f64dde75055cf8842fc4db2171eff45johnlev * notification can be made conditional on req_event (i.e., the generic
843e19887f64dde75055cf8842fc4db2171eff45johnlev * hold-off mechanism provided by the ring macros). Backends must set
843e19887f64dde75055cf8842fc4db2171eff45johnlev * req_event appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()).
843e19887f64dde75055cf8842fc4db2171eff45johnlev * Back->front notifications: When enqueuing a new response, sending a
843e19887f64dde75055cf8842fc4db2171eff45johnlev * notification can be made conditional on rsp_event (i.e., the generic
843e19887f64dde75055cf8842fc4db2171eff45johnlev * hold-off mechanism provided by the ring macros). Frontends must set
843e19887f64dde75055cf8842fc4db2171eff45johnlev * rsp_event appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()).
843e19887f64dde75055cf8842fc4db2171eff45johnlev * REQUEST CODES.
843e19887f64dde75055cf8842fc4db2171eff45johnlev * Recognised only if "feature-barrier" is present in backend xenbus info.
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * The "feature-barrier" node contains a boolean indicating whether barrier
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * requests are likely to succeed or fail. Either way, a barrier request
843e19887f64dde75055cf8842fc4db2171eff45johnlev * may fail at any time with BLKIF_RSP_EOPNOTSUPP if it is unsupported by
843e19887f64dde75055cf8842fc4db2171eff45johnlev * the underlying block-device hardware. The boolean simply indicates whether
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * or not it is worthwhile for the frontend to attempt barrier requests.
843e19887f64dde75055cf8842fc4db2171eff45johnlev * If a backend does not recognise BLKIF_OP_WRITE_BARRIER, it should *not*
843e19887f64dde75055cf8842fc4db2171eff45johnlev * create the "feature-barrier" node!
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * Recognised if "feature-flush-cache" is present in backend xenbus
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * info. A flush will ask the underlying storage hardware to flush its
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * non-volatile caches as appropriate. The "feature-flush-cache" node
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * contains a boolean indicating whether flush requests are likely to
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * succeed or fail. Either way, a flush request may fail at any time
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * with BLKIF_RSP_EOPNOTSUPP if it is unsupported by the underlying
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * block-device hardware. The boolean simply indicates whether or not it
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * is worthwhile for the frontend to attempt flushes. If a backend does
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * not recognise BLKIF_OP_WRITE_FLUSH_CACHE, it should *not* create the
349b53dd4e695e3d833b5380540385145b2d3ae8Stuart Maybee * "feature-flush-cache" node!
843e19887f64dde75055cf8842fc4db2171eff45johnlev * Maximum scatter/gather segments per request.
843e19887f64dde75055cf8842fc4db2171eff45johnlev * This is carefully chosen so that sizeof(blkif_ring_t) <= PAGE_SIZE.
843e19887f64dde75055cf8842fc4db2171eff45johnlev * NB. This could be 12 if the ring indexes weren't stored in the same page.
ad09f8b827db90c9a0093f0b6382803fa64a5fd1Mark Johnson * NB. first_sect and last_sect in blkif_request_segment, as well as
ad09f8b827db90c9a0093f0b6382803fa64a5fd1Mark Johnson * sector_number in blkif_request, are always expressed in 512-byte units.
ad09f8b827db90c9a0093f0b6382803fa64a5fd1Mark Johnson * However they must be properly aligned to the real sector size of the
ad09f8b827db90c9a0093f0b6382803fa64a5fd1Mark Johnson * physical disk, which is reported in the "sector-size" node in the backend
ad09f8b827db90c9a0093f0b6382803fa64a5fd1Mark Johnson * xenbus info. Also the xenbus "sectors" node is expressed in 512-byte units.
a576ab5b6e08c47732b3dedca9eaa8a8cbb85720rab /* @first_sect: first sector in frame to transfer (inclusive). */
a576ab5b6e08c47732b3dedca9eaa8a8cbb85720rab /* @last_sect: last sector in frame to transfer (inclusive). */
843e19887f64dde75055cf8842fc4db2171eff45johnlev blkif_vdev_t handle; /* only for read/write requests */
843e19887f64dde75055cf8842fc4db2171eff45johnlev uint64_t id; /* private guest value, echoed in resp */
843e19887f64dde75055cf8842fc4db2171eff45johnlev blkif_sector_t sector_number;/* start sector idx on disk (r/w only) */
a576ab5b6e08c47732b3dedca9eaa8a8cbb85720rab struct blkif_request_segment seg[BLKIF_MAX_SEGMENTS_PER_REQUEST];
843e19887f64dde75055cf8842fc4db2171eff45johnlev * STATUS RETURN CODES.
843e19887f64dde75055cf8842fc4db2171eff45johnlev /* Operation not supported (only happens on barrier writes). */
843e19887f64dde75055cf8842fc4db2171eff45johnlev /* Operation failed for some unspecified reason (-EIO). */
843e19887f64dde75055cf8842fc4db2171eff45johnlev /* Operation completed successfully. */
843e19887f64dde75055cf8842fc4db2171eff45johnlev * Generate blkif ring structures and types.
843e19887f64dde75055cf8842fc4db2171eff45johnlevDEFINE_RING_TYPES(blkif, struct blkif_request, struct blkif_response);
843e19887f64dde75055cf8842fc4db2171eff45johnlev#endif /* __XEN_PUBLIC_IO_BLKIF_H__ */
843e19887f64dde75055cf8842fc4db2171eff45johnlev * Local variables:
843e19887f64dde75055cf8842fc4db2171eff45johnlev * c-set-style: "BSD"
843e19887f64dde75055cf8842fc4db2171eff45johnlev * c-basic-offset: 4
843e19887f64dde75055cf8842fc4db2171eff45johnlev * tab-width: 4
843e19887f64dde75055cf8842fc4db2171eff45johnlev * indent-tabs-mode: nil