diff --git a/libqblock/libqblock.h b/libqblock/libqblock.h new file mode 100644 index 0000000..33381d1 --- /dev/null +++ b/libqblock/libqblock.h @@ -0,0 +1,550 @@ +/* + * QEMU block layer library + * + * Copyright IBM, Corp. 2012 + * + * Authors: + * Wenchao Xia + * + * This work is licensed under the terms of the GNU LGPL, version 2 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +#ifndef LIBQBLOCK_H +#define LIBQBLOCK_H + +#include +#include +#include +#include + +#define QB_ERR_MEM_ERR (-1) +#define QB_ERR_INTERNAL_ERR (-2) +#define QB_ERR_INVALID_PARAM (-3) + +/* this library is designed around this core struct. */ +struct QBlockState; + +/* every thread would have a broker. */ +struct QBroker; + +/** + * libqblock_init: Initialize the library + */ +void libqblock_init(void); + +/** + * qb_broker_new: allocate a new broker + * + * Broker is used to pass operation to libqblock, and got feed back from it. + * + * Returns 0 on success, negative value on fail. + * + * @broker: used to receive the created struct. + */ +int qb_broker_new(struct QBroker **broker); + +/** + * qb_broker_delete: delete broker + * + * Broker will be freed and set to NULL. + * + * @broker: operation broker to be deleted. + */ +void qb_broker_delete(struct QBroker **broker); + +/** + * qb_state_new: allocate a new QBloctState struct + * + * Following qblock action were based on this struct + * + * Returns 0 if succeed, negative value on fail. + * + * @broker: operation broker. + * @qbs: used to receive the created struct. + */ +int qb_state_new(struct QBroker *broker, + struct QBlockState **qbs); + +/** + * qb_state_delete: free a QBloctState struct + * + * if it is opened, a qb_close must be called before free. + * + * @broker: operation broker. + * @qbs: pointer to the struct's pointer. + */ +void qb_state_delete(struct QBroker *broker, + struct QBlockState **qbs); + + +/* flag used in open and create */ +#define LIBQBLOCK_O_RDWR 0x0002 +/* do not use the host page cache */ +#define LIBQBLOCK_O_NOCACHE 0x0020 +/* use write-back caching */ +#define LIBQBLOCK_O_CACHE_WB 0x0040 +/* don't open the backing file */ +#define LIBQBLOCK_O_NO_BACKING 0x0100 +/* disable flushing on this disk */ +#define LIBQBLOCK_O_NO_FLUSH 0x0200 + +#define LIBQBLOCK_O_CACHE_MASK \ + (LIBQBLOCK_O_NOCACHE | LIBQBLOCK_O_CACHE_WB | LIBQBLOCK_O_NO_FLUSH) + +#define LIBQBLOCK_O_VALID_MASK \ + (LIBQBLOCK_O_RDWR | LIBQBLOCK_O_NOCACHE | LIBQBLOCK_O_CACHE_WB | \ + LIBQBLOCK_O_NO_BACKING | LIBQBLOCK_O_NO_FLUSH) + +enum QBlockProtocol { + QB_PROTO_NONE = 0, + QB_PROTO_FILE, + QB_PROTO_MAX +}; + +enum QBlockFormat { + QB_FMT_NONE = 0, + QB_FMT_COW, + QB_FMT_QED, + QB_FMT_QCOW, + QB_FMT_QCOW2, + QB_FMT_RAW, + QB_FMT_RBD, + QB_FMT_SHEEPDOG, + QB_FMT_VDI, + QB_FMT_VMDK, + QB_FMT_VPC, + QB_FMT_MAX +}; + +struct QBlockOption_prot_file { + char *filename; +}; + +union QBlockOption_prot { + struct QBlockOption_prot_file o_file; +}; + +/** + * struct QBlockOptionLoc: contains information about how to find the image + * + * @prot_type: protocol type, now only support FILE. + * @prot_op: protocol related options. + */ +struct QBlockOptionLoc { + enum QBlockProtocol prot_type; + union QBlockOption_prot prot_op; + uint8_t reserved[512]; +}; + +/** + * qb_ol_new: create a new struct QBlockOptionLoc. + * + * return 0 on success, negative on fail. + * + * @broker: operation broker. + * @op: pointer to receive the new created one. + */ +int qb_ol_new(struct QBroker *broker, + struct QBlockOptionLoc **op); + +/** + * qb_ol_delete: free a struct QBlockOptionLoc. + * + * @broker: operation broker. + * @op: pointer to the object, *op would be set to NULL. + */ +void qb_ol_delete(struct QBroker *broker, + struct QBlockOptionLoc **op); + + +/* format related options */ +struct QBlockOption_fmt_cow { + size_t virt_size; + struct QBlockOptionLoc backing_loc; +}; + +struct QBlockOption_fmt_qed { + size_t virt_size; + struct QBlockOptionLoc backing_loc; + enum QBlockFormat backing_fmt; + size_t cluster_size; /* unit is bytes */ + size_t table_size; /* unit is clusters */ +}; + +struct QBlockOption_fmt_qcow { + size_t virt_size; + struct QBlockOptionLoc backing_loc; + bool encrypt; +}; + +/* "Compatibility level (0.10 or 1.1)" */ +enum QBlockOption_fmt_qcow2_cpt { + QBO_FMT_QCOW2_CPT_NONE = 0, + QBO_FMT_QCOW2_CPT_V010, + QBO_FMT_QCOW2_CPT_V110, +}; + +/* off or metadata */ +enum QBlockOption_fmt_qcow2_prealloc { + QBO_FMT_QCOW2_PREALLOC_NONE = 0, + QBO_FMT_QCOW2_PREALLOC_OFF, + QBO_FMT_QCOW2_PREALLOC_METADATA, +}; + +struct QBlockOption_fmt_qcow2 { + size_t virt_size; + struct QBlockOptionLoc backing_loc; + enum QBlockFormat backing_fmt; + bool encrypt; + size_t cluster_size; /* unit is bytes */ + enum QBlockOption_fmt_qcow2_cpt cpt_lv; + enum QBlockOption_fmt_qcow2_prealloc pre_mode; +}; + +struct QBlockOption_fmt_raw { + size_t virt_size; +}; + +struct QBlockOption_fmt_rbd { + size_t virt_size; + size_t cluster_size; +}; + +/* off or full */ +enum QBlockOption_fmt_sheepdog_prealloc { + QBO_FMT_SD_PREALLOC_NONE = 0, + QBO_FMT_SD_PREALLOC_OFF, + QBO_FMT_SD_PREALLOC_FULL, +}; + +struct QBlockOption_fmt_sheepdog { + size_t virt_size; + struct QBlockOptionLoc backing_loc; + enum QBlockOption_fmt_sheepdog_prealloc pre_mode; +}; + +enum QBlockOption_fmt_vdi_prealloc { + QBO_FMT_VDI_PREALLOC_NONE = 0, + QBO_FMT_VDI_PREALLOC_FALSE, + QBO_FMT_VDI_PREALLOC_TRUE, +}; + +struct QBlockOption_fmt_vdi { + size_t virt_size; + size_t cluster_size; + enum QBlockOption_fmt_vdi_prealloc pre_mode; +}; + +/* whether compact to vmdk verion 6 */ +enum QBlockOption_fmt_vmdk_cpt { + QBO_FMT_VMDK_CPT_NONE = 0, + QBO_FMT_VMDK_CPT_VMDKV6_FALSE, + QBO_FMT_VMDK_CPT_VMDKV6_TRUE, +}; + +/* vmdk flat extent format, values: +"{monolithicSparse (default) | monolithicFlat | twoGbMaxExtentSparse | +twoGbMaxExtentFlat | streamOptimized} */ +enum QBlockOption_fmt_vmdk_subfmt { + QBO_FMT_VMDK_SUBFMT_MONOLITHIC_NONE = 0, + QBO_FMT_VMDK_SUBFMT_MONOLITHIC_SPARSE, + QBO_FMT_VMDK_SUBFMT_MONOLITHIC_FLAT, + QBO_FMT_VMDK_SUBFMT_TWOGBMAX_EXTENT_SPARSE, + QBO_FMT_VMDK_SUBFMT_TWOGBMAX_EXTENT_FLAT, + QBO_FMT_VMDK_SUBFMT_STREAM_OPTIMIZED, +}; + +struct QBlockOption_fmt_vmdk { + size_t virt_size; + struct QBlockOptionLoc backing_loc; + enum QBlockOption_fmt_vmdk_cpt cpt_lv; + enum QBlockOption_fmt_vmdk_subfmt subfmt; +}; + +/* "{dynamic (default) | fixed} " */ +enum QBlockOption_fmt_vpc_subfmt { + QBO_FMT_VPC_SUBFMT_NONE = 0, + QBO_FMT_VPC_SUBFMT_DYNAMIC, + QBO_FMT_VPC_SUBFMT_FIXED, +}; + +struct QBlockOption_fmt_vpc { + size_t virt_size; + enum QBlockOption_fmt_vpc_subfmt subfmt; +}; + +union QBlockOption_fmt { + struct QBlockOption_fmt_cow o_cow; + struct QBlockOption_fmt_qed o_qed; + struct QBlockOption_fmt_qcow o_qcow; + struct QBlockOption_fmt_qcow2 o_qcow2; + struct QBlockOption_fmt_raw o_raw; + struct QBlockOption_fmt_rbd o_rbd; + struct QBlockOption_fmt_sheepdog o_sheepdog; + struct QBlockOption_fmt_vdi o_vdi; + struct QBlockOption_fmt_vmdk o_vmdk; + struct QBlockOption_fmt_vpc o_vpc; +}; + +struct QBlockOptionFormat { + enum QBlockFormat fmt_type; + union QBlockOption_fmt fmt_op; + uint8_t reserved[512]; +}; + +/** + * qb_of_new: create a new QBlockOptionFormat structure. + * + * return 0 on success, negative on fail. + * + * @broker: operation broker. + * @op: pointer that will receive created struct. + */ +int qb_of_new(struct QBroker *broker, + struct QBlockOptionFormat **op); + +/** + * qb_of_delete: free QBlockOptionFormat structure. + * + * @broker: operation broker. + * @op: pointer to the struct, *op would be set to NULL. + */ +void qb_of_delete(struct QBroker *broker, + struct QBlockOptionFormat **op); + + +/** + * qb_open: open a block object. + * + * return 0 on success, negative on fail. + * + * @broker: operation broker. + * @qbs: pointer to struct QBlockState. + * @loc: location options for open, how to find the image. + * @fmt: format options, how to extract the data, only valid member now is + fmt->fmt_type, set NULL if you want auto discovery the format. + * @flag: behavior control flags. + */ +int qb_open(struct QBroker *broker, + struct QBlockState *qbs, + struct QBlockOptionLoc *loc, + struct QBlockOptionFormat *fmt, + int flag); + +/** + * qb_close: close a block object. + * + * qb_flush is automaticlly done inside. + * + * @broker: operation broker. + * @qbs: pointer to struct QBlockState. + */ +void qb_close(struct QBroker *broker, + struct QBlockState *qbs); + +/** + * qb_create: create a block image or object. + * + * Note: Create operation would not open the image automatically. + * + * return negative on fail, 0 on success. + * + * @broker: operation broker. + * @qbs: pointer to struct QBlockState. + * @loc: location options for open, how to find the image. + * @fmt: format options, how to extract the data. + * @flag: behavior control flags. + */ +int qb_create(struct QBroker *broker, + struct QBlockState *qbs, + struct QBlockOptionLoc *loc, + struct QBlockOptionFormat *fmt, + int flag); + + +/* sync access */ +/** + * qb_read: block sync read. + * + * return negative on fail, 0 on success. + * + * @broker: operation broker. + * @qbs: pointer to struct QBlockState. + * @buf: buffer that receive the content. + * @len: length to read. + * @offset: offset in the block data. + */ +int qb_read(struct QBroker *broker, + struct QBlockState *qbs, + const void *buf, + size_t len, + off_t offset); +/** + * qb_write: block sync write. + * + * return negative on fail, 0 on success. + * + * @broker: operation broker. + * @qbs: pointer to struct QBlockState. + * @buf: buffer that receive the content. + * @len: length to write. + * @offset: offset in the block data. + */ +int qb_write(struct QBroker *broker, + struct QBlockState *qbs, + const void *buf, + size_t len, + off_t offset); + +/** + * qb_flush: block sync flush. + * + * return negative on fail, 0 on success. + * + * @broker: operation broker. + * @qbs: pointer to struct QBlockState. + */ +int qb_flush(struct QBroker *broker, + struct QBlockState *qbs); + +/* AIO */ +/** + * QBAioReq: represent the AIO request fired. + */ +struct QBAioReq; + +/** + * QBAioCompFunc: call back function which would be automatically called in + * qb_aio_check if a IO complete or cancelled. + * + * @opaque: opaque data registed. + * @ret: io execution result. + */ +typedef void QBAioCompFunc(void *opaque, int ret); + +/** + * qb_aio_write: block async write. + * + * return negative on fail, 0 on success. + * + * @broker: operation broker. + * @qbs: pointer to struct QBlockState. + * @buf: buffer that receive the content. + * @len: length to write. + * @offset: offset in the block data. + * @cb: call back function after io complete, can be NULL. + * @cb_opaque: call back opaque data. + * @req: pointer to receive new created request, can be NULL. + */ +int qb_aio_write(struct QBroker *broker, + struct QBlockState *qbs, + void *buf, + size_t len, + off_t offset, + QBAioCompFunc *cb, + void *cb_opaque, + struct QBAioReq **req); + +/** + * qb_aio_read: block async read. + * + * return negative on fail, 0 on success. + * + * @broker: operation broker. + * @qbs: pointer to struct QBlockState. + * @buf: buffer that receive the content. + * @len: length to write. + * @offset: offset in the block data. + * @cb: call back function after io complete, can be NULL. + * @cb_opaque: call back opaque data. + * @req: pointer to receive new created request, can be NULL. + */ +int qb_aio_read(struct QBroker *broker, + struct QBlockState *qbs, + void *buf, + size_t len, + off_t offset, + QBAioCompFunc *cb, + void *cb_opaque, + struct QBAioReq **req); + +/** + * qb_aio_check: check if there is aio request completed, if there is, execute + * the registered QBAioCompFunc call back function. + * + * return true if there is aio request remains, false if no aio request left, + * It never fail. Note the execution sequence of submitted request is not + * guarrentted. + */ +bool qb_aio_check(struct QBroker *broker); + +/* image information */ +/** + * QBlockInfoImageStatic: information about the block image. + * + * @loc: location info. + * @fmt_type: format type. + * @virt_size: virtual size in bytes. + * @backing_loc: backing file location, its type is QB_PROT_NONE if not exist. + * @allocated_size: allocated size in bytes, negative if not available. + * @encrypt: encrypt flag. + */ +struct QBlockInfoImageStatic { + struct QBlockOptionLoc loc; + enum QBlockFormat fmt_type; + size_t virt_size; + /* advance info */ + struct QBlockOptionLoc backing_loc; + size_t allocated_size; + bool encrypt; +}; + + +/** + * qb_get_image_info: get image info. + * + * return negative on fail, 0 on success. + * + * @broker: operation broker. + * @qbs: pointer to struct QBlockState. + * @info: pointer that would receive the information. + */ +int qb_info_image_static_get(struct QBroker *broker, + struct QBlockState *qbs, + struct QBlockInfoImageStatic **info); + +/** + * qb_delete_image_info: free image info. + * + * @broker: operation broker. + * @info: pointer to the information struct. + */ +void qb_info_image_static_delete(struct QBroker *broker, + struct QBlockInfoImageStatic **info); + + +/* error handling */ +/** + * qb_error_get_human_str: get human readable erro string. + * + * return a human readable string. + * + * @broker: operation broker, must be valid. + * @buf: buf to receive the string. + * @buf_size: the size of the string buf. + */ +void qb_error_get_human_str(struct QBroker *broker, + char *buf, int buf_size); + +/** + * qb_error_get_errno: get error number, only valid when err_ret is + * QB_ERR_INTERNAL_ERR. + * + * return negative errno or 0 if last error is not QB_ERR_INTERNAL_ERR. + * + * @broker: operation broker. + */ +int qb_error_get_errno(struct QBroker *broker); +#endif