From: Wenchao Xia <xiaw...@linux.vnet.ibm.com>
This patch contains the major APIs in the library. For ABI some reserved
members were used.
Important APIs:
1 QBlockContext. This structure was used to retrieve errors, every thread
must create one first.
2 QBlockState. It stands for an block image object.
3 QBlockStaticInfo. It contains static information such as location, backing
file, size.
4 Sync I/O. It is similar to C file open, read, write and close operations.
Signed-off-by: Wenchao Xia <xiaw...@linux.vnet.ibm.com>
---
block.c | 2 +-
block.h | 1 +
libqblock/libqblock-error.c | 57 ++
libqblock/libqblock-error.h | 49 ++
libqblock/libqblock.c | 1191 +++++++++++++++++++++++++++++++++++++++++++
libqblock/libqblock.h | 341 +++++++++++++
6 files changed, 1640 insertions(+), 1 deletions(-)
diff --git a/block.c b/block.c
index e95f613..ce0068a 100644
--- a/block.c
+++ b/block.c
@@ -198,7 +198,7 @@ static void bdrv_io_limits_intercept(BlockDriverState *bs,
}
/* check if the path starts with "<protocol>:" */
-static int path_has_protocol(const char *path)
+int path_has_protocol(const char *path)
{
const char *p;
diff --git a/block.h b/block.h
index e2d89d7..45f83f9 100644
--- a/block.h
+++ b/block.h
@@ -426,4 +426,5 @@ typedef enum {
#define BLKDBG_EVENT(bs, evt) bdrv_debug_event(bs, evt)
void bdrv_debug_event(BlockDriverState *bs, BlkDebugEvent event);
+int path_has_protocol(const char *path);
#endif
diff --git a/libqblock/libqblock-error.c b/libqblock/libqblock-error.c
index e69de29..2a59970 100644
--- a/libqblock/libqblock-error.c
+++ b/libqblock/libqblock-error.c
@@ -0,0 +1,57 @@
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2012
+ *
+ * Authors:
+ * Wenchao Xia <xiaw...@linux.vnet.ibm.com>
+ *
+ * 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.
+ *
+ */
+
+#include "libqblock-error.h"
+#include "libqblock-internal.h"
+
+void qb_error_get_human_str(QBlockContext *context,
+ char *buf, size_t buf_size)
+{
+ const char *err_ret_str;
+ switch (context->err_ret) {
+ case QB_ERR_INTERNAL_ERR:
+ err_ret_str = "Internal error.";
+ break;
+ case QB_ERR_INVALID_PARAM:
+ err_ret_str = "Invalid param.";
+ break;
+ case QB_ERR_BLOCK_OUT_OF_RANGE:
+ err_ret_str = "request is out of image's range.";
+ break;
+ default:
+ err_ret_str = "Unknown error.";
+ break;
+ }
+ if (context == NULL) {
+ snprintf(buf, buf_size, "%s", err_ret_str);
+ return;
+ }
+
+ if (context->err_ret == QB_ERR_INTERNAL_ERR) {
+ snprintf(buf, buf_size, "%s %s errno [%d]. strerror [%s].",
+ err_ret_str, context->g_error->message,
+ context->err_no, strerror(-context->err_no));
+ } else {
+ snprintf(buf, buf_size, "%s %s",
+ err_ret_str, context->g_error->message);
+ }
+ return;
+}
+
+int qb_error_get_errno(QBlockContext *context)
+{
+ if (context->err_ret == QB_ERR_INTERNAL_ERR) {
+ return context->err_no;
+ }
+ return 0;
+}
diff --git a/libqblock/libqblock-error.h b/libqblock/libqblock-error.h
index e69de29..4ffd1f1 100644
--- a/libqblock/libqblock-error.h
+++ b/libqblock/libqblock-error.h
@@ -0,0 +1,49 @@
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2012
+ *
+ * Authors:
+ * Wenchao Xia <xiaw...@linux.vnet.ibm.com>
+ *
+ * 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_ERROR
+#define LIBQBLOCK_ERROR
+
+#include "libqblock-types.h"
+
+#define QB_ERR_INTERNAL_ERR (-1)
+#define QB_ERR_INVALID_PARAM (-100)
+#define QB_ERR_BLOCK_OUT_OF_RANGE (-101)
+
+/* error handling */
+/**
+ * qb_error_get_human_str: get human readable error string.
+ *
+ * return a human readable string, it would be truncated if buf is not big
+ * enough.
+ *
+ * @context: operation context, must be valid.
+ * @buf: buf to receive the string.
+ * @buf_size: the size of the string buf.
+ */
+DLL_PUBLIC
+void qb_error_get_human_str(QBlockContext *context,
+ char *buf, size_t buf_size);
+
+/**
+ * qb_error_get_errno: get error number, only valid when err_ret is
+ * QB_ERR_INTERNAL_ERR.
+ *
+ * return negative errno if last error is QB_ERR_INTERNAL_ERR, otherwise 0.
+ *
+ * @context: operation context.
+ */
+DLL_PUBLIC
+int qb_error_get_errno(QBlockContext *context);
+
+#endif
diff --git a/libqblock/libqblock.c b/libqblock/libqblock.c
index e69de29..0266d06 100644
--- a/libqblock/libqblock.c
+++ b/libqblock/libqblock.c
@@ -0,0 +1,1191 @@
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2012
+ *
+ * Authors:
+ * Wenchao Xia <xiaw...@linux.vnet.ibm.com>
+ *
+ * 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.
+ *
+ */
+
+#include <unistd.h>
+#include <stdarg.h>
+
+#include "libqblock.h"
+#include "libqblock-internal.h"
+
+#include "qemu-aio.h"
+
+#define LIBQB_FILENAME_MAX 4096
+
+typedef struct LibqblockGlobalData {
+ int init_flag;
+} LibqblockGlobalData;
+
+LibqblockGlobalData libqb_global_data;
+
+typedef struct LibqbFormatStrMapping {
+ const char *fmt_str;
+ QBlockFormat fmt_type;
+} LibqbFormatStrMapping;
+
+LibqbFormatStrMapping libqb_fmtstr_table[] = {
+ {"cow", QB_FMT_COW},
+ {"qed", QB_FMT_QED},
+ {"qcow", QB_FMT_QCOW},
+ {"qcow2", QB_FMT_QCOW2},
+ {"raw", QB_FMT_RAW},
+ {"rbd", QB_FMT_RBD},
+ {"sheepdog", QB_FMT_SHEEPDOG},
+ {"vdi", QB_FMT_VDI},
+ {"vmdk", QB_FMT_VMDK},
+ {"vpc", QB_FMT_VPC},
+ {NULL, 0},
+};
+
+__attribute__((constructor))
+static void libqblock_init(void)
+{
+ if (libqb_global_data.init_flag == 0) {
+ bdrv_init();
+ qemu_init_main_loop();
+ }
+ libqb_global_data.init_flag = 1;
+ /* Todo, add an assertion about the ABI */
+}
+
+const char *qb_fmttype2str(QBlockFormat fmt_type)
+{
+ int i = 0;
+ LibqbFormatStrMapping *tb = libqb_fmtstr_table;
+
+ while (tb[i].fmt_str != NULL) {
+ if (tb[i].fmt_type == fmt_type) {
+ return tb[i].fmt_str;
+ }
+ i++;
+ }
+ return NULL;
+}
+
+QBlockFormat qb_str2fmttype(const char *fmt_str)
+{
+ int i = 0;
+ LibqbFormatStrMapping *tb = libqb_fmtstr_table;
+
+ while (tb[i].fmt_str != NULL) {
+ if ((strcmp(fmt_str, tb[i].fmt_str) == 0)) {
+ return tb[i].fmt_type;
+ }
+ i++;
+ }
+ return QB_FMT_NONE;
+}
+
+static void set_context_err(QBlockContext *context, int err_ret,
+ const char *fmt, ...)
+{
+ va_list ap;
+
+ if (context->g_error != NULL) {
+ g_error_free(context->g_error);
+ }
+
+ va_start(ap, fmt);
+ context->g_error = g_error_new_valist(G_LIBQBLOCK_ERROR, err_ret, fmt, ap);
+ va_end(ap);
+
+ context->err_ret = err_ret;
+ if (err_ret == QB_ERR_INTERNAL_ERR) {
+ context->err_no = -errno;
+ } else {
+ context->err_no = 0;
+ }
+}
+
+int qb_context_new(QBlockContext **context)
+{
+ *context = FUNC_CALLOC(1, sizeof(QBlockContext));
+ return 0;
+}
+
+void qb_context_delete(QBlockContext **context)
+{
+ if ((*context)->g_error != NULL) {
+ g_error_free((*context)->g_error);
+ }
+ CLEAN_FREE(*context);
+ return;
+}
+
+int qb_state_new(QBlockContext *context,
+ QBlockState **qbs)
+{
+ *qbs = FUNC_CALLOC(1, sizeof(QBlockState));
+ (*qbs)->bdrvs = bdrv_new("hda");
+ if ((*qbs)->bdrvs == NULL) {
+ CLEAN_FREE(*qbs);
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "failed to create the driver.");
+ return context->err_ret;
+ }
+ return 0;
+}
+
+void qb_state_delete(QBlockContext *context,
+ QBlockState **qbs)
+{
+ if ((*qbs)->filename != NULL) {
+ qb_close(context, *qbs);
+ }
+ if ((*qbs)->bdrvs != NULL) {
+ bdrv_delete((*qbs)->bdrvs);
+ (*qbs)->bdrvs = NULL;
+ }
+ CLEAN_FREE(*qbs);
+ return;
+}
+
+int qb_loc_info_new(QBlockContext *context,
+ QBlockLocationInfo **loc)
+{
+ *loc = FUNC_CALLOC(1, sizeof(QBlockLocationInfo));
+ return 0;
+}
+
+void qb_loc_info_delete(QBlockContext *context,
+ QBlockLocationInfo **loc)
+{
+ CLEAN_FREE(*loc);
+}
+
+int qb_fmt_info_new(QBlockContext *context,
+ QBlockFormatInfo **fmt)
+{
+ *fmt = FUNC_CALLOC(1, sizeof(QBlockFormatInfo));
+ return 0;
+}
+
+void qb_fmt_info_delete(QBlockContext *context,
+ QBlockFormatInfo **fmt)
+{
+ CLEAN_FREE(*fmt);
+}
+
+/* return 0 if every thing is fine */
+static int loc_check_params(QBlockContext *context,
+ QBlockLocationInfo *loc)
+{
+ context->err_ret = 0;
+
+ switch (loc->prot_type) {
+ case QB_PROTO_FILE:
+ if (loc->o_file.filename == NULL) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Filename was not set.");
+ goto out;
+ }
+ if (path_has_protocol(loc->o_file.filename) > 0) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "filename [%s] had protocol.",
+ loc->o_file.filename);
+ goto out;
+ }
+ break;
+ default:
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Protocol type [%d] was not valid.",
+ loc->prot_type);
+ break;
+ }
+
+ out:
+ return context->err_ret;
+}
+
+/* translate loc structure to internal filename, returned char* need free,
+ * assuming filename is not NULL. *filename would be set to NULL if no valid
+ * filename found. *filename must be freed later.
+ * return 0 if no error with *filename set.
+ */
+static int loc2filename(QBlockContext *context,
+ QBlockLocationInfo *loc,
+ char **filename)
+{
+ context->err_ret = 0;
+
+ if (*filename != NULL) {
+ CLEAN_FREE(*filename);
+ }
+ switch (loc->prot_type) {
+ case QB_PROTO_FILE:
+ *filename = FUNC_STRDUP(loc->o_file.filename);
+ break;
+ default:
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "protocol type [%d] is not supported.",
+ loc->prot_type);
+ break;
+ }
+
+ return context->err_ret;
+}
+
+/* translate filename to location, loc->prot_type = NONE if fail, filename
+ must be valid. loc internal char pointer must be freed later.
+ * return 0 if no error.
+ */
+static int filename2loc(QBlockContext *context,
+ QBlockLocationInfo *loc,
+ const char *filename)
+{
+ context->err_ret = 0;
+
+ if (path_has_protocol(filename) > 0) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Filename [%s] had protocol, not supported now.",
+ filename);
+ goto out;
+ }
+
+ loc->prot_type = QB_PROTO_FILE;
+ switch (loc->prot_type) {
+ case QB_PROTO_FILE:
+ loc->o_file.filename = FUNC_STRDUP(filename);
+ break;
+ default:
+ break;
+ }
+
+ out:
+ return context->err_ret;
+}
+
+/* return 0 if OK, or qblock error number */
+static int set_backing_file_options(QBlockContext *context,
+ QEMUOptionParameter *param,
+ QBlockLocationInfo *loc,
+ QBlockFormat *fmt)
+{
+ char *backing_filename = NULL;
+ const char *fmtstr_backing = NULL;
+ int ret = 0;
+
+ if (loc == NULL) {
+ goto out;
+ }
+
+ ret = loc2filename(context, loc, &backing_filename);
+ /* ret can < 0 if loc have not been set, mean user did not specify backing
+ file, so need to check return value */
+
+ ret = 0;
+
+ if (backing_filename) {
+ ret = set_option_parameter(param,
+ BLOCK_OPT_BACKING_FILE, backing_filename);
+ assert(ret == 0);
+ if (fmt == NULL) {
+ goto out;
+ }
+ fmtstr_backing = qb_fmttype2str(*fmt);
+ if (fmtstr_backing) {
+ ret = set_option_parameter(param,
+ BLOCK_OPT_BACKING_FMT, fmtstr_backing);
+ assert(ret == 0);
+ }
+ }
+
+ out:
+ FUNC_FREE(backing_filename);
+ return ret;
+}
+
+int qb_create(QBlockContext *context,
+ QBlockState *qbs,
+ QBlockLocationInfo *loc,
+ QBlockFormatInfo *fmt,
+ int flag)
+{
+ int ret = 0, bd_ret;
+ char *filename = NULL;
+ BlockDriverState *bs = NULL;
+ BlockDriver *drv = NULL, *backing_drv = NULL;
+ bool tmp_bool;
+
+ const char *fmtstr = NULL, *tmp = NULL;
+ QEMUOptionParameter *param = NULL, *create_options = NULL;
+ QEMUOptionParameter *backing_fmt, *backing_file, *size;
+ QBlockFormatOptionsCOW *o_cow = NULL;
+ QBlockFormatOptionsQED *o_qed = NULL;
+ QBlockFormatOptionsQCOW *o_qcow = NULL;
+ QBlockFormatOptionsQCOW2 *o_qcow2 = NULL;
+ QBlockFormatOptionsRAW *o_raw = NULL;
+ QBlockFormatOptionsRBD *o_rbd = NULL;
+ QBlockFormatOptionsSD *o_sd = NULL;
+ QBlockFormatOptionsVDI *o_vdi = NULL;
+ QBlockFormatOptionsVMDK *o_vmdk = NULL;
+ QBlockFormatOptionsVPC *o_vpc = NULL;
+
+
+ /* check parameters */
+ if (flag & (~LIBQBLOCK_O_VALID_MASK)) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "invalid flag was set.");
+ ret = context->err_ret;
+ goto out;
+ }
+
+ if ((loc == NULL) || (qbs == NULL) || (fmt == NULL)) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Got unexpected NULL pointer in parameters.");
+ ret = context->err_ret;
+ goto out;
+ }
+
+ ret = loc_check_params(context, loc);
+ if (ret != 0) {
+ goto out;
+ }
+
+ /* internal translate */
+ ret = loc2filename(context, loc, &filename);
+ if (ret != 0) {
+ goto out;
+ }
+
+ fmtstr = qb_fmttype2str(fmt->fmt_type);
+ if (fmtstr == NULL) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Got unexpected NULL pointer in parameters.");
+ ret = context->err_ret;
+ goto out;
+ }
+
+ drv = bdrv_find_format(fmtstr);
+ assert(drv != NULL);
+
+ create_options = append_option_parameters(create_options,
+ drv->create_options);
+ param = parse_option_parameters("", create_options, param);
+
+ switch (fmt->fmt_type) {
+ case QB_FMT_COW:
+ o_cow = &(fmt->o_cow);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_cow->virt_size);
+ assert(bd_ret == 0);
+ /* do not need to check loc, it may be not set */
+ ret = set_backing_file_options(context, param,
+ &o_cow->backing_loc, NULL);
+ if (ret != 0) {
+ goto out;
+ }
+ break;
+ case QB_FMT_QED:
+ o_qed = &(fmt->o_qed);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_qed->virt_size);
+ assert(bd_ret == 0);
+ ret = set_backing_file_options(context, param,
+ &o_qed->backing_loc, &o_qed->backing_fmt);
+ if (ret != 0) {
+ goto out;
+ }
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_CLUSTER_SIZE, o_qed->cluster_size);
+ assert(bd_ret == 0);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_TABLE_SIZE, o_qed->table_size);
+ assert(bd_ret == 0);
+ break;
+ case QB_FMT_QCOW:
+ o_qcow = &(fmt->o_qcow);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_qcow->virt_size);
+ assert(bd_ret == 0);
+ ret = set_backing_file_options(context, param,
+ &o_qcow->backing_loc, NULL);
+ if (ret != 0) {
+ goto out;
+ }
+ tmp = o_qcow->encrypt ? "on" : "off";
+ bd_ret = set_option_parameter(param, BLOCK_OPT_ENCRYPT, tmp);
+ assert(bd_ret == 0);
+ break;
+ case QB_FMT_QCOW2:
+ o_qcow2 = &(fmt->o_qcow2);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_qcow2->virt_size);
+ assert(bd_ret == 0);
+ ret = set_backing_file_options(context, param,
+ &o_qcow2->backing_loc, &o_qcow2->backing_fmt);
+ if (ret != 0) {
+ goto out;
+ }
+ tmp = o_qcow2->encrypt ? "on" : "off";
+ bd_ret = set_option_parameter(param, BLOCK_OPT_ENCRYPT, tmp);
+ assert(bd_ret == 0);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_CLUSTER_SIZE, o_qcow2->cluster_size);
+ assert(bd_ret == 0);
+
+ if (o_qcow2->cpt_lv != QB_FMT_QCOW2_COMPAT_DEFAULT) {
+ tmp = o_qcow2->cpt_lv == QB_FMT_QCOW2_COMPAT_V0_10 ? "0.10" :
"1.1";
+ bd_ret = set_option_parameter(param,
+ BLOCK_OPT_COMPAT_LEVEL, tmp);
+ assert(bd_ret == 0);
+ }
+
+ if (o_qcow2->pre_mode != QB_FMT_QCOW2_PREALLOC_DEFAULT) {
+ tmp = o_qcow2->pre_mode == QB_FMT_QCOW2_PREALLOC_OFF ?
+ "off" : "metadata";
+ bd_ret = set_option_parameter(param,
+ BLOCK_OPT_PREALLOC, tmp);
+ assert(bd_ret == 0);
+ }
+ break;
+
+ case QB_FMT_RAW:
+ o_raw = &(fmt->o_raw);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_raw->virt_size);
+ assert(bd_ret == 0);
+ break;
+ case QB_FMT_RBD:
+ o_rbd = &(fmt->o_rbd);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_rbd->virt_size);
+ assert(bd_ret == 0);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_CLUSTER_SIZE, o_rbd->cluster_size);
+ assert(bd_ret == 0);
+ break;
+ case QB_FMT_SHEEPDOG:
+ o_sd = &(fmt->o_sd);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_sd->virt_size);
+ assert(bd_ret == 0);
+ ret = set_backing_file_options(context, param,
+ &o_sd->backing_loc, NULL);
+ if (ret != 0) {
+ goto out;
+ }
+ if (o_sd->pre_mode != QB_FMT_SD_PREALLOC_DEFAULT) {
+ tmp = o_sd->pre_mode == QB_FMT_SD_PREALLOC_OFF ? "off" : "full";
+ bd_ret = set_option_parameter(param,
+ BLOCK_OPT_PREALLOC, tmp);
+ assert(bd_ret == 0);
+ }
+ break;
+ case QB_FMT_VDI:
+ o_vdi = &(fmt->o_vdi);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_vdi->virt_size);
+ assert(bd_ret == 0);
+ /* following option is not always valid depends on configuration */
+ set_option_parameter_int(param,
+ BLOCK_OPT_CLUSTER_SIZE, o_vdi->cluster_size);
+ if (o_vdi->pre_mode != QB_FMT_VDI_PREALLOC_DEFAULT) {
+ tmp_bool = o_sd->pre_mode == QB_FMT_VDI_PREALLOC_METADATA ?
+ true : false;
+ set_option_parameter_int(param, "static", tmp_bool);
+ }
+ break;
+ case QB_FMT_VMDK:
+ o_vmdk = &(fmt->o_vmdk);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_vmdk->virt_size);
+ assert(bd_ret == 0);
+ ret = set_backing_file_options(context, param,
+ &o_vmdk->backing_loc, NULL);
+ if (ret != 0) {
+ goto out;
+ }
+
+ if (o_vmdk->cpt_lv != QB_FMT_VMDK_COMPAT_DEFAULT) {
+ tmp_bool = o_vmdk->cpt_lv == QB_FMT_VMDK_COMPAT_VMDKV6_TRUE ?
+ true : false;
+ bd_ret = set_option_parameter_int(param, BLOCK_OPT_COMPAT6,
+ tmp_bool);
+ assert(bd_ret == 0);
+ }
+ if (o_vmdk->subfmt != QB_FMT_VMDK_SUBFMT_DEFAULT) {
+ switch (o_vmdk->subfmt) {
+ case QB_FMT_VMDK_SUBFMT_MONOLITHIC_SPARSE:
+ tmp = "monolithicSparse";
+ break;
+ case QB_FMT_VMDK_SUBFMT_MONOLITHIC_FLAT:
+ tmp = "monolithicFlat";
+ break;
+ case QB_FMT_VMDK_SUBFMT_TWOGBMAX_EXTENT_SPARSE:
+ tmp = "twoGbMaxExtentSparse";
+ break;
+ case QB_FMT_VMDK_SUBFMT_TWOGBMAX_EXTENT_FLAT:
+ tmp = "twoGbMaxExtentFlat";
+ break;
+ case QB_FMT_VMDK_SUBFMT_STREAM_OPTIMIZED:
+ tmp = "streamOptimized";
+ break;
+ default:
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "invalid VMDK sumfmt type %d was set.", o_vmdk->subfmt);
+ ret = context->err_ret;
+ goto out;
+ break;
+ }
+ bd_ret = set_option_parameter(param,
+ BLOCK_OPT_SUBFMT, tmp);
+ assert(bd_ret == 0);
+ }
+ break;
+ case QB_FMT_VPC:
+ o_vpc = &(fmt->o_vpc);
+ bd_ret = set_option_parameter_int(param,
+ BLOCK_OPT_SIZE, o_vpc->virt_size);
+ assert(bd_ret == 0);
+ if (o_vpc->subfmt != QB_FMT_VPC_SUBFMT_DEFAULT) {
+ tmp = o_vpc->subfmt == QB_FMT_VPC_SUBFMT_DYNAMIC ?
+ "dynamic" : "fixed";
+ bd_ret = set_option_parameter(param,
+ BLOCK_OPT_SUBFMT, tmp);
+ assert(bd_ret == 0);
+ }
+ break;
+ default:
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "invalid format type %d was set.", fmt->fmt_type);
+ ret = context->err_ret;
+ goto out;
+ break;
+ }
+
+ backing_file = get_option_parameter(param, BLOCK_OPT_BACKING_FILE);
+ if (backing_file && backing_file->value.s) {
+ if (!strcmp(filename, backing_file->value.s)) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Backing file is the same with new file.");
+ ret = context->err_ret;
+ goto out;
+ }
+ }
+
+ backing_fmt = get_option_parameter(param, BLOCK_OPT_BACKING_FMT);
+ if (backing_fmt && backing_fmt->value.s) {
+ backing_drv = bdrv_find_format(backing_fmt->value.s);
+ assert(backing_drv != NULL);
+ }
+
+ size = get_option_parameter(param, BLOCK_OPT_SIZE);
+ if (size && size->value.n <= 0) {
+ if (backing_file && backing_file->value.s) {
+ uint64_t size;
+ char buf[32];
+ int back_flags;
+
+ /* backing files always opened read-only */
+ back_flags =
+ flag &
+ ~(BDRV_O_RDWR | BDRV_O_SNAPSHOT | BDRV_O_NO_BACKING);
+
+ bs = bdrv_new("");
+
+ ret = bdrv_open(bs, backing_file->value.s,
+ back_flags, backing_drv);
+ if (ret < 0) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Failed to open the backing file.");
+ ret = context->err_ret;
+ goto out;
+ }
+ bdrv_get_geometry(bs, &size);
+ size *= BDRV_SECTOR_SIZE;
+
+ snprintf(buf, sizeof(buf), "%" PRId64, size);
+ set_option_parameter(param, BLOCK_OPT_SIZE, buf);
+ } else {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "Neither size or backing file was not set.");
+ ret = context->err_ret;
+ goto out;
+ }
+ }
+
+ bd_ret = bdrv_create(drv, filename, param);
+
+
+ if (bd_ret < 0) {
+ const char *errstr;
+ if (bd_ret == -ENOTSUP) {
+ errstr = "formatting option not supported.";
+ } else if (bd_ret == -EFBIG) {
+ errstr = "The image size is too large.";
+ } else {
+ errstr = "Error in creating the image.";
+ }
+ set_context_err(context, QB_ERR_INTERNAL_ERR, errstr);
+ ret = context->err_ret;
+ }
+
+out:
+ free_option_parameters(create_options);
+ free_option_parameters(param);
+ FUNC_FREE(filename);
+ if (bs) {
+ bdrv_delete(bs);
+ }
+
+ return ret;
+}
+
+int qb_open(QBlockContext *context,
+ QBlockState *qbs,
+ QBlockLocationInfo *loc,
+ QBlockFormatInfo *fmt,
+ int flag)
+{
+ int ret = 0, bd_ret;
+ BlockDriverState *bs;
+ BlockDriver *bd;
+ const char *fmtstr;
+ char *filename = NULL;
+
+ /* take care of user settings */
+ /* do nothing now */
+
+ /* check parameters */
+ if (flag & (~LIBQBLOCK_O_VALID_MASK)) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Invalid flag was set.");
+ ret = context->err_ret;
+ goto out;
+ }
+
+ if ((loc == NULL) || (qbs == NULL)) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Got unexpected NULL pointer in parameters.");
+ ret = context->err_ret;
+ goto out;
+ }
+
+ ret = loc_check_params(context, loc);
+ if (ret != 0) {
+ goto out;
+ }
+
+ /* internal translate */
+ ret = loc2filename(context, loc, &filename);
+ if (ret != 0) {
+ goto out;
+ }
+
+ fmtstr = NULL;
+ bd = NULL;
+ if (fmt != NULL) {
+ fmtstr = qb_fmttype2str(fmt->fmt_type);
+ }
+
+ if (fmtstr != NULL) {
+ bd = bdrv_find_format(fmtstr);
+ assert(bd != NULL);
+ }
+
+ /* do real opening */
+ bs = qbs->bdrvs;
+ bd_ret = bdrv_open(bs, filename, flag, bd);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "Failed in opening with driver, bd_ret is %d.", bd_ret);
+ ret = context->err_ret;
+ goto out;
+ }
+
+ if (qbs->filename != NULL) {
+ FUNC_FREE(qbs->filename);
+ }
+ qbs->filename = FUNC_STRDUP(filename);
+
+ out:
+ FUNC_FREE(filename);
+ return ret;
+}
+
+void qb_close(QBlockContext *context,
+ QBlockState *qbs)
+{
+ BlockDriverState *bs;
+
+ bs = qbs->bdrvs;
+
+ if (qbs->filename != NULL) {
+ CLEAN_FREE(qbs->filename);
+ bdrv_close(bs);
+ }
+ return;
+}
+
+int32_t qb_read(QBlockContext *context,
+ QBlockState *qbs,
+ uint8_t *buf,
+ uint32_t len,
+ uint64_t offset)
+{
+ int bd_ret;
+ BlockDriverState *bs;
+ uint8_t temp_buf[BDRV_SECTOR_SIZE], *p;
+ uint64_t sector_start;
+ int sector_num, byte_offset, cp_len;
+ uint32_t remains;
+
+ context->err_ret = 0;
+ bs = qbs->bdrvs;
+
+ if (len <= 0) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Param len is less or equal to zero.");
+ return context->err_ret;
+ }
+
+ p = buf;
+ remains = len;
+
+ sector_start = offset >> BDRV_SECTOR_BITS;
+
+ byte_offset = offset & (~BDRV_SECTOR_MASK);
+ if (byte_offset != 0) {
+ /* the start sector is not alligned, need to read/write this sector. */
+ bd_ret = bdrv_read(bs, sector_start, temp_buf, 1);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "QEMU internal block error.");
+ context->err_no = bd_ret;
+ return context->err_ret;
+ }
+ cp_len = BDRV_SECTOR_SIZE - byte_offset;
+ memcpy(p, temp_buf + byte_offset, cp_len);
+
+ remains -= cp_len;
+ p += cp_len;
+ sector_start++;
+ }
+
+ /* now start position is alligned. */
+ if (remains >= BDRV_SECTOR_SIZE) {
+ sector_num = remains >> BDRV_SECTOR_BITS;
+ bd_ret = bdrv_read(bs, sector_start, p, sector_num);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "QEMU internal block error.");
+ context->err_no = bd_ret;
+ return context->err_ret;
+ }
+ remains -= sector_num << BDRV_SECTOR_BITS;
+ p += sector_num << BDRV_SECTOR_BITS;
+ sector_start += sector_num;
+ }
+
+ if (remains > 0) {
+ /* there is some request remains, less than 1 sector */
+ bd_ret = bdrv_read(bs, sector_start, temp_buf, 1);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "QEMU internal block error.");
+ context->err_no = bd_ret;
+ return context->err_ret;
+ }
+ memcpy(p, temp_buf, remains);
+ remains -= remains;
+ }
+
+ return len-remains;
+}
+
+int32_t qb_write(QBlockContext *context,
+ QBlockState *qbs,
+ const uint8_t *buf,
+ uint32_t len,
+ uint64_t offset)
+{
+ int bd_ret;
+ BlockDriverState *bs;
+ uint8_t temp_buf[BDRV_SECTOR_SIZE];
+ const uint8_t *p;
+ uint64_t sector_start;
+ int sector_num, byte_offset, cp_len;
+ uint32_t remains;
+
+ context->err_ret = 0;
+ bs = qbs->bdrvs;
+
+ if (len <= 0) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Param len is less or equal to zero.");
+ return context->err_ret;
+ }
+
+ p = buf;
+ remains = len;
+
+ sector_start = offset >> BDRV_SECTOR_BITS;
+
+ byte_offset = offset & (~BDRV_SECTOR_MASK);
+ if (byte_offset != 0) {
+ /* the start sector is not alligned, need to read/write this sector. */
+ bd_ret = bdrv_read(bs, sector_start, temp_buf, 1);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "QEMU internal block error.");
+ context->err_no = bd_ret;
+ return context->err_ret;
+ }
+ cp_len = BDRV_SECTOR_SIZE - byte_offset;
+ memcpy(temp_buf + byte_offset, p, cp_len);
+ bd_ret = bdrv_write(bs, sector_start, temp_buf, 1);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "QEMU internal block error.");
+ context->err_no = bd_ret;
+ return context->err_ret;
+ }
+ remains -= cp_len;
+ p += cp_len;
+ sector_start++;
+ }
+
+ /* now start position is alligned. */
+ if (remains >= BDRV_SECTOR_SIZE) {
+ sector_num = remains >> BDRV_SECTOR_BITS;
+ bd_ret = bdrv_write(bs, sector_start, p, sector_num);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "QEMU internal block error.");
+ context->err_no = bd_ret;
+ return context->err_ret;
+ }
+ remains -= sector_num << BDRV_SECTOR_BITS;
+ p += sector_num << BDRV_SECTOR_BITS;
+ sector_start += sector_num;
+ }
+
+ if (remains > 0) {
+ /* there is some request remains, less than 1 sector */
+ bd_ret = bdrv_read(bs, sector_start, temp_buf, 1);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "QEMU internal block error.");
+ context->err_no = bd_ret;
+ return context->err_ret;
+ }
+ memcpy(temp_buf, p, remains);
+ bd_ret = bdrv_write(bs, sector_start, temp_buf, 1);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "QEMU internal block error.");
+ context->err_no = bd_ret;
+ return context->err_ret;
+ }
+ remains -= remains;
+ }
+
+ return len-remains;
+}
+
+int qb_flush(QBlockContext *context,
+ QBlockState *qbs)
+{
+ int bd_ret;
+ BlockDriverState *bs;
+
+ context->err_ret = 0;
+ bs = qbs->bdrvs;
+ bd_ret = bdrv_flush(bs);
+ if (bd_ret < 0) {
+ set_context_err(context, QB_ERR_INTERNAL_ERR,
+ "Internal error.");
+ }
+ return context->err_ret;
+}
+
+int qb_check_allocation(QBlockContext *context,
+ QBlockState *qbs,
+ uint64_t start,
+ int64_t length,
+ int *pstatus,
+ int64_t *plength)
+{
+ int ret;
+ int sector_start, sector_num, num;
+ BlockDriverState *bs;
+ unsigned int real_len, ret_len;
+
+ context->err_ret = 0;
+ bs = qbs->bdrvs;
+
+ if (length > 0x1000000000000) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "length is too big.");
+ goto out;
+ }
+
+ if (qbs->filename == NULL) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Image was not opened first.");
+ goto out;
+ }
+
+ if (length <= 0) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "length is not valid.");
+ goto out;
+ }
+
+ /* translate to sector */
+ sector_start = start >> BDRV_SECTOR_BITS;
+ real_len = (start & (~BDRV_SECTOR_MASK)) + length;
+ sector_num = real_len >> BDRV_SECTOR_BITS;
+ if ((real_len & (~BDRV_SECTOR_MASK)) != 0) {
+ sector_num++;
+ }
+
+ ret = bdrv_is_allocated(bs, sector_start, sector_num, &num);
+ if ((ret == 0) && (num == 0)) {
+ set_context_err(context, QB_ERR_BLOCK_OUT_OF_RANGE,
+ "Start position was bigger than the image's size.");
+ goto out;
+ }
+
+ *pstatus = ret;
+ ret_len = (num << BDRV_SECTOR_BITS) - (start & (~BDRV_SECTOR_MASK));
+ if (ret_len > length) {
+ ret_len = length;
+ }
+ *plength = ret_len;
+
+ out:
+ return context->err_ret;
+}
+
+static void qb_setup_info_addr(const QBlockStaticInfo *info,
+ QBlockStaticInfoAddr *info_addr)
+{
+ const uint64_t *virt_size = NULL;
+ const QBlockLocationInfo *backing_loc = NULL;
+ const bool *encrypt = NULL;
+ const QBlockFormatInfo *fmt = &(info->fmt);
+
+ switch (fmt->fmt_type) {
+ case QB_FMT_COW:
+ virt_size = &(fmt->o_cow.virt_size);
+ backing_loc = &(fmt->o_cow.backing_loc);
+ break;
+ case QB_FMT_QED:
+ virt_size = &(fmt->o_qed.virt_size);
+ backing_loc = &(fmt->o_qed.backing_loc);
+ break;
+ case QB_FMT_QCOW:
+ virt_size = &(fmt->o_qcow.virt_size);
+ backing_loc = &(fmt->o_qcow.backing_loc);
+ encrypt = &(fmt->o_qcow.encrypt);
+ break;
+ case QB_FMT_QCOW2:
+ virt_size = &(fmt->o_qcow2.virt_size);
+ backing_loc = &(fmt->o_qcow2.backing_loc);
+ encrypt = &(fmt->o_qcow2.encrypt);
+ break;
+ case QB_FMT_RAW:
+ virt_size = &(fmt->o_raw.virt_size);
+ break;
+ case QB_FMT_RBD:
+ virt_size = &(fmt->o_rbd.virt_size);
+ break;
+ case QB_FMT_SHEEPDOG:
+ virt_size = &(fmt->o_sd.virt_size);
+ backing_loc = &(fmt->o_sd.backing_loc);
+ break;
+ case QB_FMT_VDI:
+ virt_size = &(fmt->o_vdi.virt_size);
+ break;
+ case QB_FMT_VMDK:
+ virt_size = &(fmt->o_vmdk.virt_size);
+ backing_loc = &(fmt->o_vmdk.backing_loc);
+ break;
+ case QB_FMT_VPC:
+ virt_size = &(fmt->o_vpc.virt_size);
+ break;
+ default:
+ break;
+ }
+
+ info_addr->virt_size = (uint64_t *)virt_size;
+ info_addr->backing_loc = (QBlockLocationInfo *)backing_loc;
+ info_addr->encrypt = (bool *)encrypt;
+ return;
+}
+
+const uint64_t *qb_get_virt_size(const QBlockStaticInfo *info)
+{
+ QBlockStaticInfoAddr addr;
+ memset(&addr, 0, sizeof(QBlockStaticInfoAddr));
+ qb_setup_info_addr(info, &addr);
+ return addr.virt_size;
+}
+
+const QBlockLocationInfo *qb_get_backing_loc(const QBlockStaticInfo *info)
+{
+ QBlockStaticInfoAddr addr;
+ memset(&addr, 0, sizeof(QBlockStaticInfoAddr));
+ qb_setup_info_addr(info, &addr);
+ return addr.backing_loc;
+}
+
+const bool *qb_get_encrypt(const QBlockStaticInfo *info)
+{
+ QBlockStaticInfoAddr addr;
+ memset(&addr, 0, sizeof(QBlockStaticInfoAddr));
+ qb_setup_info_addr(info, &addr);
+ return addr.encrypt;
+}
+
+int qb_info_image_static_get(QBlockContext *context,
+ QBlockState *qbs,
+ QBlockStaticInfo **info)
+{
+ int ret = 0;
+ BlockDriverState *bs;
+ QBlockStaticInfo *info_tmp;
+ QBlockStaticInfoAddr *member_addr, addr;
+ const char *fmt_str;
+ uint64_t total_sectors;
+ char backing_filename[LIBQB_FILENAME_MAX];
+
+ if (qbs->filename == NULL) {
+ set_context_err(context, QB_ERR_INVALID_PARAM,
+ "Block Image was not openned.");
+ ret = context->err_ret;
+ goto out;
+ }
+
+ info_tmp = FUNC_CALLOC(1, sizeof(QBlockStaticInfo));
+
+ bs = qbs->bdrvs;
+
+ ret = filename2loc(context,
+ &(info_tmp->loc),
+ qbs->filename);
+ if (ret < 0) {
+ goto free;
+ }
+
+ fmt_str = bdrv_get_format_name(bs);
+ info_tmp->fmt.fmt_type = qb_str2fmttype(fmt_str);
+ /* we got the format type and basic location info now, setup the struct
+ pointer to the internal members */
+ memset(&addr, 0, sizeof(QBlockStaticInfoAddr));
+ member_addr = &addr;
+ qb_setup_info_addr(info_tmp, member_addr);
+
+ assert(member_addr->virt_size != NULL);
+ bdrv_get_geometry(bs, &total_sectors);
+ *(member_addr->virt_size) = total_sectors * BDRV_SECTOR_SIZE;
+
+ if (member_addr->encrypt != NULL) {
+ *(member_addr->encrypt) = bdrv_is_encrypted(bs);
+ }
+
+ bdrv_get_full_backing_filename(bs, backing_filename,
+ sizeof(backing_filename));
+ if (backing_filename[0] != '\0') {
+ assert(member_addr->backing_loc != NULL);
+ ret = filename2loc(context,
+ member_addr->backing_loc,
+ backing_filename);
+ if (ret < 0) {
+ goto free;
+ }
+ }
+
+ info_tmp->sector_size = BDRV_SECTOR_SIZE;
+ *info = info_tmp;
+
+ out:
+ return ret;
+ free:
+ qb_info_image_static_delete(context, &info_tmp);
+ return ret;
+}
+
+/* free locations if it has string allocated on heap. */
+static void loc_free(QBlockLocationInfo *loc)
+{
+ switch (loc->prot_type) {
+ case QB_PROTO_FILE:
+ FUNC_FREE((void *)(loc->o_file.filename));
+ loc->o_file.filename = NULL;
+ break;
+ default:
+ break;
+ }
+}
+
+/* free fmt related resoure. */
+static void fmt_free(QBlockFormatInfo *fmt)
+{
+ switch (fmt->fmt_type) {
+ case QB_FMT_COW:
+ loc_free(&(fmt->o_cow.backing_loc));
+ break;
+ case QB_FMT_QED:
+ loc_free(&(fmt->o_qed.backing_loc));
+ break;
+ case QB_FMT_QCOW:
+ loc_free(&(fmt->o_qcow.backing_loc));
+ break;
+ case QB_FMT_QCOW2:
+ loc_free(&(fmt->o_qcow2.backing_loc));
+ break;
+ case QB_FMT_RAW:
+ break;
+ case QB_FMT_RBD:
+ break;
+ case QB_FMT_SHEEPDOG:
+ loc_free(&(fmt->o_sd.backing_loc));
+ break;
+ case QB_FMT_VDI:
+ break;
+ case QB_FMT_VMDK:
+ loc_free(&(fmt->o_vmdk.backing_loc));
+ break;
+ case QB_FMT_VPC:
+ break;
+ default:
+ break;
+ }
+ return;
+}
+
+
+void qb_info_image_static_delete(QBlockContext *context,
+ QBlockStaticInfo **info)
+{
+ loc_free(&(*info)->loc);
+ fmt_free(&(*info)->fmt);
+ CLEAN_FREE(*info);
+}
+
+QBlockLocationInfo *qb_loc_info_dup(const QBlockLocationInfo *prot)
+{
+ QBlockLocationInfo *p = FUNC_CALLOC(1, sizeof(QBlockLocationInfo));
+ p->prot_type = prot->prot_type;
+ switch (p->prot_type) {
+ case QB_PROTO_FILE:
+ p->o_file.filename =
+ FUNC_STRDUP(prot->o_file.filename);
+ break;
+ default:
+ break;
+ }
+ return p;
+}
diff --git a/libqblock/libqblock.h b/libqblock/libqblock.h
index e69de29..8ca7d28 100644
--- a/libqblock/libqblock.h
+++ b/libqblock/libqblock.h
@@ -0,0 +1,341 @@
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2012
+ *
+ * Authors:
+ * Wenchao Xia <xiaw...@linux.vnet.ibm.com>
+ *
+ * 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 "libqblock-types.h"
+#include "libqblock-error.h"
+
+/**
+ * qb_context_new: allocate a new context.
+ *
+ * Broker is used to pass operation to libqblock, and get feedback from it.
+ *
+ * Returns 0 on success, libqblock negative error value on fail.
+ *
+ * @context: used to receive the created struct.
+ */
+DLL_PUBLIC
+int qb_context_new(QBlockContext **context);
+
+/**
+ * qb_context_delete: delete context.
+ *
+ * Broker will be freed and set to NULL.
+ *
+ * @context: operation context to be deleted.
+ */
+DLL_PUBLIC
+void qb_context_delete(QBlockContext **context);
+
+/**
+ * qb_state_new: allocate a new QBlockState struct
+ *
+ * Subsequent qblock actions will use this struct
+ *
+ * Returns 0 if succeed, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @qbs: used to receive the created struct.
+ */
+DLL_PUBLIC
+int qb_state_new(QBlockContext *context,
+ QBlockState **qbs);
+
+/**
+ * qb_state_delete: free a QBlockState struct
+ *
+ * if image was opened, qb_close should be called before delete, otherwise
+ * it would be automatically closed.
+ *
+ * @context: operation context.
+ * @qbs: pointer to the struct's pointer.
+ */
+DLL_PUBLIC
+void qb_state_delete(QBlockContext *context,
+ QBlockState **qbs);
+
+/**
+ * qb_loc_info_new: create a new QBlockLocationInfo object.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @loc: pointer to receive the new created one.
+ */
+DLL_PUBLIC
+int qb_loc_info_new(QBlockContext *context,
+ QBlockLocationInfo **loc);
+
+/**
+ * qb_loc_info_delete: free a QBlockLocationInfo.
+ *
+ * @context: operation context.
+ * @loc: pointer to the object, *loc would be set to NULL.
+ */
+DLL_PUBLIC
+void qb_loc_info_delete(QBlockContext *context,
+ QBlockLocationInfo **loc);
+
+/**
+ * qb_fmt_info_new: create a new QBlockFormatInfo structure.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @op: pointer that will receive created struct.
+ */
+DLL_PUBLIC
+int qb_fmt_info_new(QBlockContext *context,
+ QBlockFormatInfo **fmt);
+
+/**
+ * qb_fmt_info_delete: free QBlockFormatInfo structure.
+ *
+ * @context: operation context.
+ * @fmt: pointer to the struct, *fmt would be set to NULL.
+ */
+DLL_PUBLIC
+void qb_fmt_info_delete(QBlockContext *context,
+ QBlockFormatInfo **fmt);
+
+
+/**
+ * qb_open: open a block object.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @qbs: pointer to 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 to NULL if you want to auto discovery the format.
+ * @flag: behavior control flags, it is LIBQBLOCK_O_XXX's combination.
+ *
+ * Note: For raw image, there is a risk that it's content is changed to some
+ * magic value resulting a wrong probing done by libqblock, so don't do
+ * probing on raw images.
+ */
+DLL_PUBLIC
+int qb_open(QBlockContext *context,
+ QBlockState *qbs,
+ QBlockLocationInfo *loc,
+ QBlockFormatInfo *fmt,
+ int flag);
+
+/**
+ * qb_close: close a block object.
+ *
+ * qb_flush is automatically done inside.
+ *
+ * @context: operation context.
+ * @qbs: pointer to QBlockState.
+ */
+DLL_PUBLIC
+void qb_close(QBlockContext *context,
+ QBlockState *qbs);
+
+/**
+ * qb_create: create a block image or object.
+ *
+ * Note: Create operation would not open the image automatically.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @qbs: pointer to QBlockState.
+ * @loc: location options for open, how to find the image.
+ * @fmt: format options, how to extract the data.
+ * @flag: behavior control flags, LIBQBLOCK_O_XXX's combination.
+ */
+DLL_PUBLIC
+int qb_create(QBlockContext *context,
+ QBlockState *qbs,
+ QBlockLocationInfo *loc,
+ QBlockFormatInfo *fmt,
+ int flag);
+
+
+/* sync access */
+/**
+ * qb_read: block sync read.
+ *
+ * return number of bytes read, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @qbs: pointer to QBlockState.
+ * @buf: buffer that receive the content.
+ * @len: length to read.
+ * @offset: offset in the block data.
+ */
+DLL_PUBLIC
+int32_t qb_read(QBlockContext *context,
+ QBlockState *qbs,
+ uint8_t *buf,
+ uint32_t len,
+ uint64_t offset);
+
+/**
+ * qb_write: block sync write.
+ *
+ * return number of bytes written, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @qbs: pointer to QBlockState.
+ * @buf: buffer that receive the content.
+ * @len: length to write.
+ * @offset: offset in the block data.
+ */
+DLL_PUBLIC
+int32_t qb_write(QBlockContext *context,
+ QBlockState *qbs,
+ const uint8_t *buf,
+ uint32_t len,
+ uint64_t offset);
+
+/**
+ * qb_flush: block sync flush.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @qbs: pointer to QBlockState.
+ */
+DLL_PUBLIC
+int qb_flush(QBlockContext *context,
+ QBlockState *qbs);
+
+
+/* advance image APIs */
+/**
+ * qb_check_allocation: check if [start, start+lenth-1] was allocated on the
+ * image.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @qbs: pointer to QBlockState.
+ * @start: start position, unit is byte.
+ * @length: length to check, unit is byte, max is 1TB, otherwise will return
+ * QB_ERR_INVALID_PARAM.
+ * @pstatus: pointer to receive the status, 1 means allocated,
+ * 0 means unallocated.
+ * @plength: pointer to receive the length that all have the same status as
+ * *pstatus.
+ *
+ * Note: after return, start+*plength may have the same status as
+ * start+*plength-1.
+ */
+DLL_PUBLIC
+int qb_check_allocation(QBlockContext *context,
+ QBlockState *qbs,
+ uint64_t start,
+ int64_t length,
+ int *pstatus,
+ int64_t *plength);
+
+/* image information */
+/**
+ * qb_get_image_info: get image info.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @qbs: pointer to QBlockState.
+ * @info: pointer that would receive the information.
+ *
+ * *info must be not modified after return, qb_info_image_static_delete will
+ * use the information in it.
+ */
+DLL_PUBLIC
+int qb_info_image_static_get(QBlockContext *context,
+ QBlockState *qbs,
+ QBlockStaticInfo **info);
+
+/**
+ * qb_delete_image_info: free image info.
+ *
+ * @context: operation context.
+ * @info: pointer to the information struct.
+ */
+DLL_PUBLIC
+void qb_info_image_static_delete(QBlockContext *context,
+ QBlockStaticInfo **info);
+
+/* helper functions */
+/**
+ * qb_str2fmttype: translate format string to libqblock format enum type.
+ *
+ * return the type, or QB_FMT_NONE if string matches none of supported types.
+ *
+ * @fmt: the format string.
+ */
+DLL_PUBLIC
+QBlockFormat qb_str2fmttype(const char *fmt_str);
+
+/**
+ * qb_fmttype2str: translate libqblock format enum type to a string.
+ *
+ * return a pointer to the string, or NULL if type is not supported, and
+ * returned pointer must NOT be freed.
+ *
+ * @fmt: the format enum type.
+ */
+DLL_PUBLIC
+const char *qb_fmttype2str(QBlockFormat fmt_type);
+
+/**
+ * qb_loc_info_dup: duplicate a QBlockLocationInfo instance.
+ *
+ * return a pointer to new allocated one having the same values with input,
+ * it need to be freed by qb_loc_info_delete later. Never fail except OOM.
+ *
+ * @loc: pointer to the source instance.
+ */
+DLL_PUBLIC
+QBlockLocationInfo *qb_loc_info_dup(const QBlockLocationInfo *loc);
+
+/**
+ * qb_get_virt_size: get virtual size.
+ *
+ * return a pointer, which pointer to a member in info, or NULL if info is
+ * not valid.
+ *
+ * @info: pointer to the QBlockStaticInfo structure.
+ */
+DLL_PUBLIC
+const uint64_t *qb_get_virt_size(const QBlockStaticInfo *info);
+
+/**
+ * qb_get_backing_loc: get backing file location.
+ *
+ * return a pointer, which pointer to a member in info, or NULL if info is
+ * not valid, or image have no such property.
+ *
+ * @info: pointer to the QBlockStaticInfo structure.
+ */
+DLL_PUBLIC
+const QBlockLocationInfo *qb_get_backing_loc(const QBlockStaticInfo *info);
+
+/**
+ * qb_get_encrypt: get encrytion flag.
+ *
+ * return a pointer, which pointer to a member in info, or NULL if info is
+ * not valid, or image have no such property.
+ *
+ * @info: pointer to the QBlockStaticInfo structure.
+ */
+DLL_PUBLIC
+const bool *qb_get_encrypt(const QBlockStaticInfo *info);
+#endif
--
1.7.1
