Patchwork [V4,3/5] libqblock API

login
register
mail settings
Submitter Wayne Xia
Date Sept. 27, 2012, 2:24 a.m.
Message ID <1348712642-4427-4-git-send-email-xiawenc@linux.vnet.ibm.com>
Download mbox | patch
Permalink /patch/187262/
State New
Headers show

Comments

Wayne Xia - Sept. 27, 2012, 2:24 a.m.
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 <xiawenc@linux.vnet.ibm.com>
---
 block.c                     |    2 +-
 block.h                     |    1 +
 libqblock/libqblock-error.c |   57 +++
 libqblock/libqblock-error.h |   49 ++
 libqblock/libqblock.c       | 1165 +++++++++++++++++++++++++++++++++++++++++++
 libqblock/libqblock.h       |  308 ++++++++++++
 6 files changed, 1581 insertions(+), 1 deletions(-)
 create mode 100644 libqblock/libqblock-error.h
 create mode 100644 libqblock/libqblock.h

Patch

diff --git a/block.c b/block.c
index 751ebdc..24ae396 100644
--- a/block.c
+++ b/block.c
@@ -196,7 +196,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 b1095d8..de6818f 100644
--- a/block.h
+++ b/block.h
@@ -423,4 +423,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   <xiawenc@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
new file mode 100644
index 0000000..4ffd1f1
--- /dev/null
+++ b/libqblock/libqblock-error.h
@@ -0,0 +1,49 @@ 
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2012
+ *
+ * Authors:
+ *  Wenchao Xia   <xiawenc@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..ebb1dff 100644
--- a/libqblock/libqblock.c
+++ b/libqblock/libqblock.c
@@ -0,0 +1,1165 @@ 
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2012
+ *
+ * Authors:
+ *  Wenchao Xia   <xiawenc@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 LibqbFmtStrMapping {
+    const char *fmt_str;
+    QBlockFmtType fmt_type;
+} LibqbFmtStrMapping;
+
+LibqbFmtStrMapping 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;
+    g_assert(sizeof(QBlockFmtOptionsUnion) == QBLOCK_FMT_OPTIONS_UNION_SIZE);
+    g_assert(sizeof(QBlockProtOptionsUnion) == QBLOCK_PROT_OPTIONS_UNION_SIZE);
+}
+
+const char *qb_fmttype2str(QBlockFmtType fmt_type)
+{
+    int i = 0;
+    LibqbFmtStrMapping *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;
+}
+
+QBlockFmtType qb_str2fmttype(const char *fmt_str)
+{
+    int i = 0;
+    LibqbFmtStrMapping *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_prot_info_new(QBlockContext *context,
+                     QBlockProtInfo **op)
+{
+    *op = FUNC_CALLOC(1, sizeof(QBlockProtInfo));
+    return 0;
+}
+
+void qb_prot_info_delete(QBlockContext *context,
+                         QBlockProtInfo **op)
+{
+    CLEAN_FREE(*op);
+}
+
+int qb_fmt_info_new(QBlockContext *context,
+                    QBlockFmtInfo **op)
+{
+    *op = FUNC_CALLOC(1, sizeof(QBlockFmtInfo));
+    return 0;
+}
+
+void qb_fmt_info_delete(QBlockContext *context,
+                        QBlockFmtInfo **op)
+{
+    CLEAN_FREE(*op);
+}
+
+/* return 0 if every thing is fine */
+static int loc_check_params(QBlockContext *context,
+                            QBlockProtInfo *loc)
+{
+    context->err_ret = 0;
+
+    switch (loc->prot_type) {
+    case QB_PROT_FILE:
+        if (loc->prot_op.o_file.filename == NULL) {
+            set_context_err(context, QB_ERR_INVALID_PARAM,
+                           "Filename was not set.");
+            goto out;
+        }
+        if (path_has_protocol(loc->prot_op.o_file.filename) > 0) {
+            set_context_err(context, QB_ERR_INVALID_PARAM,
+                           "filename [%s] had protocol.",
+                           loc->prot_op.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,
+                        QBlockProtInfo *loc,
+                        char **filename)
+{
+    context->err_ret = 0;
+
+    if (*filename != NULL) {
+        CLEAN_FREE(*filename);
+    }
+    switch (loc->prot_type) {
+    case QB_PROT_FILE:
+        *filename = FUNC_STRDUP(loc->prot_op.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,
+                        QBlockProtInfo *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_PROT_FILE;
+    switch (loc->prot_type) {
+    case QB_PROT_FILE:
+        loc->prot_op.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,
+                                    QBlockProtInfo *loc,
+                                    QBlockFmtType *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,
+              QBlockProtInfo *loc,
+              QBlockFmtInfo *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;
+    QBlockFmtOptionCow *o_cow = NULL;
+    QBlockFmtOptionQed *o_qed = NULL;
+    QBlockFmtOptionQcow *o_qcow = NULL;
+    QBlockFmtOptionQcow2 *o_qcow2 = NULL;
+    QBlockFmtOptionRaw *o_raw = NULL;
+    QBlockFmtOptionRbd *o_rbd = NULL;
+    QBlockFmtOptionSheepdog *o_sd = NULL;
+    QBlockFmtOptionVdi *o_vdi = NULL;
+    QBlockFmtOptionVmdk *o_vmdk = NULL;
+    QBlockFmtOptionVpc *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->fmt_op.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->fmt_op.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->fmt_op.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->fmt_op.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 != QBO_FMT_QCOW2_CPT_NONE) {
+            tmp = o_qcow2->cpt_lv == QBO_FMT_QCOW2_CPT_V010 ? "0.10" : "1.1";
+            bd_ret = set_option_parameter(param,
+                              BLOCK_OPT_COMPAT_LEVEL, tmp);
+            assert(bd_ret == 0);
+        }
+
+        if (o_qcow2->pre_mode != QBO_FMT_QCOW2_PREALLOC_NONE) {
+            tmp = o_qcow2->pre_mode == QBO_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->fmt_op.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->fmt_op.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->fmt_op.o_sheepdog);
+        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 != QBO_FMT_SD_PREALLOC_NONE) {
+            tmp = o_sd->pre_mode == QBO_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->fmt_op.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 != QBO_FMT_VDI_PREALLOC_NONE) {
+            tmp_bool = o_sd->pre_mode == QBO_FMT_VDI_PREALLOC_TRUE ?
+                                                     true : false;
+            set_option_parameter_int(param, "static", tmp_bool);
+        }
+        break;
+    case QB_FMT_VMDK:
+        o_vmdk = &(fmt->fmt_op.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 != QBO_FMT_VMDK_CPT_NONE) {
+            tmp_bool = o_vmdk->cpt_lv == QBO_FMT_VMDK_CPT_VMDKV6_TRUE ?
+                                                     true : false;
+            bd_ret = set_option_parameter_int(param, BLOCK_OPT_COMPAT6,
+                                                     tmp_bool);
+            assert(bd_ret == 0);
+        }
+        if (o_vmdk->subfmt != QBO_FMT_VMDK_SUBFMT_MONOLITHIC_NONE) {
+            switch (o_vmdk->subfmt) {
+            case QBO_FMT_VMDK_SUBFMT_MONOLITHIC_SPARSE:
+                tmp = "monolithicSparse";
+                break;
+            case QBO_FMT_VMDK_SUBFMT_MONOLITHIC_FLAT:
+                tmp = "monolithicFlat";
+                break;
+            case QBO_FMT_VMDK_SUBFMT_TWOGBMAX_EXTENT_SPARSE:
+                tmp = "twoGbMaxExtentSparse";
+                break;
+            case QBO_FMT_VMDK_SUBFMT_TWOGBMAX_EXTENT_FLAT:
+                tmp = "twoGbMaxExtentFlat";
+                break;
+            case QBO_FMT_VMDK_SUBFMT_STREAM_OPTIMIZED:
+                tmp = "streamOptimized";
+                break;
+            default:
+                assert(false);
+                break;
+            }
+            bd_ret = set_option_parameter(param,
+                              BLOCK_OPT_SUBFMT, tmp);
+            assert(bd_ret == 0);
+        }
+        break;
+    case QB_FMT_VPC:
+        o_vpc = &(fmt->fmt_op.o_vpc);
+        bd_ret = set_option_parameter_int(param,
+                               BLOCK_OPT_SIZE, o_vpc->virt_size);
+        assert(bd_ret == 0);
+        if (o_vpc->subfmt != QBO_FMT_VPC_SUBFMT_NONE) {
+            tmp = o_vpc->subfmt == QBO_FMT_VPC_SUBFMT_DYNAMIC ?
+                                               "dynamic" : "fixed";
+            bd_ret = set_option_parameter(param,
+                               BLOCK_OPT_SUBFMT, tmp);
+            assert(bd_ret == 0);
+        }
+        break;
+    default:
+        abort();
+        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,
+            QBlockProtInfo *loc,
+            QBlockFmtInfo *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(QBlockStaticInfo *info,
+                               QBlockStaticInfoAddr *info_addr)
+{
+    uint64_t *virt_size = NULL;
+    QBlockProtInfo *backing_loc = NULL;
+    bool *encrypt = NULL;
+    QBlockFmtInfo *fmt = &(info->fmt);
+
+    switch (fmt->fmt_type) {
+    case QB_FMT_COW:
+        virt_size = &(fmt->fmt_op.o_cow.virt_size);
+        backing_loc = &(fmt->fmt_op.o_cow.backing_loc);
+        break;
+    case QB_FMT_QED:
+        virt_size = &(fmt->fmt_op.o_qed.virt_size);
+        backing_loc = &(fmt->fmt_op.o_qed.backing_loc);
+        break;
+    case QB_FMT_QCOW:
+        virt_size = &(fmt->fmt_op.o_qcow.virt_size);
+        backing_loc = &(fmt->fmt_op.o_qcow.backing_loc);
+        encrypt = &(fmt->fmt_op.o_qcow.encrypt);
+        break;
+    case QB_FMT_QCOW2:
+        virt_size = &(fmt->fmt_op.o_qcow2.virt_size);
+        backing_loc = &(fmt->fmt_op.o_qcow2.backing_loc);
+        encrypt = &(fmt->fmt_op.o_qcow2.encrypt);
+        break;
+    case QB_FMT_RAW:
+        virt_size = &(fmt->fmt_op.o_raw.virt_size);
+        break;
+    case QB_FMT_RBD:
+        virt_size = &(fmt->fmt_op.o_rbd.virt_size);
+        break;
+    case QB_FMT_SHEEPDOG:
+        virt_size = &(fmt->fmt_op.o_sheepdog.virt_size);
+        backing_loc = &(fmt->fmt_op.o_sheepdog.backing_loc);
+        break;
+    case QB_FMT_VDI:
+        virt_size = &(fmt->fmt_op.o_vdi.virt_size);
+        break;
+    case QB_FMT_VMDK:
+        virt_size = &(fmt->fmt_op.o_vmdk.virt_size);
+        backing_loc = &(fmt->fmt_op.o_vmdk.backing_loc);
+        break;
+    case QB_FMT_VPC:
+        virt_size = &(fmt->fmt_op.o_vpc.virt_size);
+        break;
+    default:
+        break;
+    }
+
+    info_addr->virt_size = virt_size;
+    info_addr->backing_loc = backing_loc;
+    info_addr->encrypt = encrypt;
+    return;
+}
+
+int qb_info_image_static_get(QBlockContext *context,
+                             QBlockState *qbs,
+                             QBlockStaticInfo **info)
+{
+    int ret = 0;
+    BlockDriverState *bs;
+    QBlockStaticInfo *info_tmp;
+    QBlockStaticInfoAddr *member_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 */
+    member_addr = FUNC_CALLOC(1, sizeof(QBlockStaticInfoAddr));
+    qb_setup_info_addr(info_tmp, member_addr);
+    info_tmp->member_addr = 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(QBlockProtInfo *loc)
+{
+    switch (loc->prot_type) {
+    case QB_PROT_FILE:
+        FUNC_FREE((void *)(loc->prot_op.o_file.filename));
+        loc->prot_op.o_file.filename = NULL;
+        break;
+    default:
+        break;
+    }
+}
+
+/* free fmt related resoure. */
+static void fmt_free(QBlockFmtInfo *fmt)
+{
+    switch (fmt->fmt_type) {
+    case QB_FMT_COW:
+        loc_free(&(fmt->fmt_op.o_cow.backing_loc));
+        break;
+    case QB_FMT_QED:
+        loc_free(&(fmt->fmt_op.o_qed.backing_loc));
+        break;
+    case QB_FMT_QCOW:
+        loc_free(&(fmt->fmt_op.o_qcow.backing_loc));
+        break;
+    case QB_FMT_QCOW2:
+        loc_free(&(fmt->fmt_op.o_qcow2.backing_loc));
+        break;
+    case QB_FMT_RAW:
+        break;
+    case QB_FMT_RBD:
+        break;
+    case QB_FMT_SHEEPDOG:
+        loc_free(&(fmt->fmt_op.o_sheepdog.backing_loc));
+        break;
+    case QB_FMT_VDI:
+        break;
+    case QB_FMT_VMDK:
+        loc_free(&(fmt->fmt_op.o_vmdk.backing_loc));
+        break;
+    case QB_FMT_VPC:
+        break;
+    default:
+        break;
+    }
+    return;
+}
+
+
+void qb_info_image_static_delete(QBlockContext *context,
+                                 QBlockStaticInfo **info)
+{
+    if ((*info)->member_addr != NULL) {
+        FUNC_FREE((*info)->member_addr);
+    }
+    loc_free(&(*info)->loc);
+    fmt_free(&(*info)->fmt);
+    CLEAN_FREE(*info);
+}
+
+QBlockProtInfo *qb_prot_info_dup(const QBlockProtInfo *prot)
+{
+    QBlockProtInfo *p = FUNC_CALLOC(1, sizeof(QBlockProtInfo));
+    p->prot_type = prot->prot_type;
+    switch (p->prot_type) {
+    case QB_PROT_FILE:
+        p->prot_op.o_file.filename =
+                          FUNC_STRDUP(prot->prot_op.o_file.filename);
+        break;
+    default:
+        break;
+    }
+    return p;
+}
diff --git a/libqblock/libqblock.h b/libqblock/libqblock.h
new file mode 100644
index 0000000..9a6ed75
--- /dev/null
+++ b/libqblock/libqblock.h
@@ -0,0 +1,308 @@ 
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2012
+ *
+ * Authors:
+ *  Wenchao Xia   <xiawenc@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_prot_info_new: create a new QBlockProtInfo object.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @op: pointer to receive the new created one.
+ */
+DLL_PUBLIC
+int qb_prot_info_new(QBlockContext *context,
+                     QBlockProtInfo **op);
+
+/**
+ * qb_prot_info_delete: free a QBlockProtInfo.
+ *
+ * @context: operation context.
+ * @op: pointer to the object, *op would be set to NULL.
+ */
+DLL_PUBLIC
+void qb_prot_info_delete(QBlockContext *context,
+                         QBlockProtInfo **op);
+
+/**
+ * qb_fmt_info_new: create a new QBlockFmtInfo 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,
+                    QBlockFmtInfo **op);
+
+/**
+ * qb_fmt_info_delete: free QBlockFmtInfo structure.
+ *
+ * @context: operation context.
+ * @op: pointer to the struct, *op would be set to NULL.
+ */
+DLL_PUBLIC
+void qb_fmt_info_delete(QBlockContext *context,
+                        QBlockFmtInfo **op);
+
+
+/**
+ * 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,
+            QBlockProtInfo *loc,
+            QBlockFmtInfo *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,
+              QBlockProtInfo *loc,
+              QBlockFmtInfo *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
+QBlockFmtType 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(QBlockFmtType fmt_type);
+
+/**
+ * qb_prot_info_dup: duplicate a QBlockProtInfo instance.
+ *
+ * return a pointer to new allocated one having the same values with input,
+ *  it need to be freed by qb_prot_info_delete later. Never fail except OOM.
+ *
+ * @prot: pointer to the source instance.
+ */
+DLL_PUBLIC
+QBlockProtInfo *qb_prot_info_dup(const QBlockProtInfo *prot);
+#endif