[Qemu-devel] [PATCH V15 6/9] libqblock: libqblock API design and type defines

[Wenchao Xia]

  Public API design header files: libqblock.h, libqblock-error.h.
Public type define header files: libqblock-types.h. Private internal used
header files: libqblock-internal. For ABI some reserved bytes are used in
structure defines. Macro LIBQB_DLL_PUBLIC was used to export symbols.

Important APIs:
  1 QBlockContext. This structure was used to retrieve errors, every thread
must create one first.
  2 QBlockImage. 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 <address@hidden>
---
 libqblock/libqblock-error.h    |   49 ++++++
 libqblock/libqblock-internal.h |   68 ++++++++
 libqblock/libqblock-types.h    |  245 +++++++++++++++++++++++++++
 libqblock/libqblock.h          |  355 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 717 insertions(+), 0 deletions(-)
 create mode 100644 libqblock/libqblock-internal.h

diff --git a/libqblock/libqblock-error.h b/libqblock/libqblock-error.h
index e69de29..3fe9e40 100644
--- a/libqblock/libqblock-error.h
+++ b/libqblock/libqblock-error.h
@@ -0,0 +1,49 @@
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2013
+ *
+ * Authors:
+ *  Wenchao Xia   <address@hidden>
+ *
+ * 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.
+ */
+LIBQB_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.
+ */
+LIBQB_DLL_PUBLIC
+int qb_error_get_errno(QBlockContext *context);
+
+#endif
diff --git a/libqblock/libqblock-internal.h b/libqblock/libqblock-internal.h
new file mode 100644
index 0000000..91521f5
--- /dev/null
+++ b/libqblock/libqblock-internal.h
@@ -0,0 +1,68 @@
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2013
+ *
+ * Authors:
+ *  Wenchao Xia   <address@hidden>
+ *
+ * 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_INTERNAL
+#define LIBQBLOCK_INTERNAL
+
+#include <glib.h>
+
+#include "block/block.h"
+#include "libqblock-types.h"
+
+/* this file contains defines and types used inside the library. */
+
+#define QB_FREE(p) { \
+        g_free(p); \
+        (p) = NULL; \
+}
+
+/* details should be hidden to user */
+struct QBlockImage {
+    BlockDriverState *bdrvs;
+    /* internal used file name now, if it is not NULL, it means
+       image was opened.
+    */
+    char *filename;
+    int ref_count;
+};
+
+struct QBlockContext {
+    /* last error */
+    GError *g_error;
+    int err_ret; /* 1st level of error, the libqblock error number */
+    int err_no; /* 2nd level of error, errno what below reports */
+};
+
+/**
+ * QBlockStaticInfoAddr: a structure contains a set of pointer.
+ *
+ *    this struct contains a set of pointer pointing to some
+ *  property related to format or protocol. If a property is not available,
+ *  it will be set as NULL. User could use this to get properties directly.
+ *
+ *  @backing_loc: backing file location.
+ *  @encrypt: encryption flag.
+*/
+
+typedef struct QBlockStaticInfoAddr {
+    QBlockLocationInfo *backing_loc;
+    bool *encrypt;
+} QBlockStaticInfoAddr;
+
+#define G_LIBQBLOCK_ERROR g_libqblock_error_quark()
+
+static inline GQuark g_libqblock_error_quark(void)
+{
+    return g_quark_from_static_string("g-libqblock-error-quark");
+}
+#endif
diff --git a/libqblock/libqblock-types.h b/libqblock/libqblock-types.h
index e69de29..20504ea 100644
--- a/libqblock/libqblock-types.h
+++ b/libqblock/libqblock-types.h
@@ -0,0 +1,245 @@
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2013
+ *
+ * Authors:
+ *  Wenchao Xia   <address@hidden>
+ *
+ * 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_TYPES_H
+#define LIBQBLOCK_TYPES_H
+
+#include <sys/types.h>
+#include <stdint.h>
+#include <stdbool.h>
+
+#if defined(__GNUC__) && __GNUC__ >= 4
+    #ifdef LIBQB_BUILD
+        #define LIBQB_DLL_PUBLIC __attribute__((__visibility__("default")))
+    #else
+        #define LIBQB_DLL_PUBLIC
+    #endif
+#endif
+
+/* this library is designed around this core struct. */
+typedef struct QBlockImage QBlockImage;
+
+/* every thread should have a context. */
+typedef struct QBlockContext QBlockContext;
+
+/* 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)
+
+typedef enum QBlockProtocol {
+    QB_PROTO_NONE = 0,
+    QB_PROTO_FILE,
+    QB_PROTO_MAX
+} QBlockProtocol;
+
+typedef struct QBlockProtocolOptionsFile {
+    const char *filename;
+} QBlockProtocolOptionsFile;
+
+/**
+ * struct QBlockLocationInfo: contains information about how to find the image
+ *
+ * @prot_type: protocol type, now only support FILE.
+ * @o_file: file protocol related attributes.
+ * @reserved: reserved bytes for ABI.
+ */
+#define QBLOCK_PROT_OPTIONS_UNION_SIZE (512)
+typedef struct QBlockLocationInfo {
+    QBlockProtocol prot_type;
+    union {
+        QBlockProtocolOptionsFile o_file;
+        uint64_t reserved[QBLOCK_PROT_OPTIONS_UNION_SIZE/sizeof(uint64_t)];
+    };
+} QBlockLocationInfo;
+
+
+/* format related options */
+typedef 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
+} QBlockFormat;
+
+typedef struct QBlockFormatOptionsCOW {
+    QBlockLocationInfo backing_loc;
+} QBlockFormatOptionsCOW;
+
+typedef struct QBlockFormatOptionsQED {
+    QBlockLocationInfo backing_loc;
+    QBlockFormat backing_fmt;
+    uint64_t cluster_size; /* unit is bytes */
+    uint64_t table_size; /* unit is clusters */
+} QBlockFormatOptionsQED;
+
+typedef struct QBlockFormatOptionsQCOW {
+    QBlockLocationInfo backing_loc;
+    bool encrypt;
+} QBlockFormatOptionsQCOW;
+
+/* "Compatibility level (0.10 or 1.1)" */
+typedef enum QBlockFormatOptionsQCOW2CompatLv {
+    QB_FMT_QCOW2_COMPAT_DEFAULT = 0,
+    QB_FMT_QCOW2_COMPAT_V0_10,
+    QB_FMT_QCOW2_COMPAT_V1_10,
+} QBlockFormatOptionsQCOW2CompatLv;
+
+/* off or metadata */
+typedef enum QBlockFormatOptionsQCOW2PreAlloc {
+    QB_FMT_QCOW2_PREALLOC_DEFAULT = 0,
+    QB_FMT_QCOW2_PREALLOC_OFF,
+    QB_FMT_QCOW2_PREALLOC_METADATA,
+} QBlockFormatOptionsQCOW2PreAlloc;
+
+typedef struct QBlockFormatOptionsQCOW2 {
+    QBlockLocationInfo backing_loc;
+    QBlockFormat backing_fmt;
+    bool encrypt;
+    uint64_t cluster_size; /* unit is bytes */
+    QBlockFormatOptionsQCOW2CompatLv cpt_lv;
+    QBlockFormatOptionsQCOW2PreAlloc pre_mode;
+} QBlockFormatOptionsQCOW2;
+
+typedef struct QBlockFormatOptionsRAW {
+    int reserved;
+} QBlockFormatOptionsRAW;
+
+typedef struct QBlockFormatOptionsRBD {
+    uint64_t cluster_size;
+} QBlockFormatOptionsRBD;
+
+/* off or full */
+typedef enum QBlockFormatOptionsSDPreAlloc {
+    QB_FMT_SD_PREALLOC_DEFAULT = 0,
+    QB_FMT_SD_PREALLOC_OFF,
+    QB_FMT_SD_PREALLOC_FULL,
+} QBlockFormatOptionsSDPreAlloc;
+
+typedef struct QBlockFormatOptionsSD {
+    QBlockLocationInfo backing_loc;
+    QBlockFormatOptionsSDPreAlloc pre_mode;
+} QBlockFormatOptionsSD;
+
+typedef enum QBlockFormatOptionsVDIPreAlloc {
+    QB_FMT_VDI_PREALLOC_DEFAULT = 0,
+    QB_FMT_VDI_PREALLOC_OFF,
+    QB_FMT_VDI_PREALLOC_METADATA,
+} QBlockFormatOptionsVDIPreAlloc;
+
+typedef struct QBlockFormatOptionsVDI {
+    uint64_t cluster_size;
+    QBlockFormatOptionsVDIPreAlloc pre_mode;
+} QBlockFormatOptionsVDI;
+
+/* whether compact to vmdk version 6 */
+typedef enum QBlockFormatOptionsVMDKCompatLv {
+    QB_FMT_VMDK_COMPAT_DEFAULT = 0,
+    QB_FMT_VMDK_COMPAT_VMDKV6_FALSE,
+    QB_FMT_VMDK_COMPAT_VMDKV6_TRUE,
+} QBlockFormatOptionsVMDKCompatLv;
+
+/* vmdk flat extent format, values:
+"{monolithicSparse (default) | monolithicFlat | twoGbMaxExtentSparse |
+twoGbMaxExtentFlat | streamOptimized} */
+typedef enum QBlockFormatOptionsVMDKSubfmt {
+    QB_FMT_VMDK_SUBFMT_DEFAULT = 0,
+    QB_FMT_VMDK_SUBFMT_MONOLITHIC_SPARSE,
+    QB_FMT_VMDK_SUBFMT_MONOLITHIC_FLAT,
+    QB_FMT_VMDK_SUBFMT_TWOGBMAX_EXTENT_SPARSE,
+    QB_FMT_VMDK_SUBFMT_TWOGBMAX_EXTENT_FLAT,
+    QB_FMT_VMDK_SUBFMT_STREAM_OPTIMIZED,
+} QBlockFormatOptionsVMDKSubfmt;
+
+typedef struct QBlockFormatOptionsVMDK {
+    QBlockLocationInfo backing_loc;
+    QBlockFormatOptionsVMDKCompatLv cpt_lv;
+    QBlockFormatOptionsVMDKSubfmt subfmt;
+} QBlockFormatOptionsVMDK;
+
+/* "{dynamic (default) | fixed} " */
+typedef enum QBlockFormatOptionsVPCSubfmt {
+    QB_FMT_VPC_SUBFMT_DEFAULT = 0,
+    QB_FMT_VPC_SUBFMT_DYNAMIC,
+    QB_FMT_VPC_SUBFMT_FIXED,
+} QBlockFormatOptionsVPCSubfmt;
+
+typedef struct QBlockFormatOptionsVPC {
+    QBlockFormatOptionsVPCSubfmt subfmt;
+} QBlockFormatOptionsVPC;
+
+#define QBLOCK_FMT_OPTIONS_UNION_SIZE (QBLOCK_PROT_OPTIONS_UNION_SIZE*2)
+
+/**
+ * struct QBlockFormatInfo: contains information about how to retrieve data
+ *  from the image
+ *
+ * @virt_size: image virtual size.
+ * @fmt_type: format type.
+ * @address@hidden: format related attributes.
+ * @reserved: reserved bytes for ABI.
+ */
+typedef struct QBlockFormatInfo {
+    uint64_t virt_size;
+    QBlockFormat fmt_type;
+    union {
+        QBlockFormatOptionsCOW       o_cow;
+        QBlockFormatOptionsQED       o_qed;
+        QBlockFormatOptionsQCOW      o_qcow;
+        QBlockFormatOptionsQCOW2     o_qcow2;
+        QBlockFormatOptionsRAW       o_raw;
+        QBlockFormatOptionsRBD       o_rbd;
+        QBlockFormatOptionsSD        o_sd;
+        QBlockFormatOptionsVDI       o_vdi;
+        QBlockFormatOptionsVMDK      o_vmdk;
+        QBlockFormatOptionsVPC       o_vpc;
+        uint64_t reserved[QBLOCK_FMT_OPTIONS_UNION_SIZE/sizeof(uint64_t)];
+    };
+} QBlockFormatInfo;
+
+/**
+ * QBlockStaticInfo: information about the block image.
+ *
+ * @loc: location information.
+ * @fmt: format information.
+ * @sector_size: how many bytes in a sector, it is 512 usually.
+ */
+typedef struct QBlockStaticInfo {
+    QBlockLocationInfo loc;
+    QBlockFormatInfo fmt;
+    int sector_size;
+} QBlockStaticInfo;
+
+
+#endif
diff --git a/libqblock/libqblock.h b/libqblock/libqblock.h
index e69de29..439338c 100644
--- a/libqblock/libqblock.h
+++ b/libqblock/libqblock.h
@@ -0,0 +1,355 @@
+/*
+ * QEMU block layer library
+ *
+ * Copyright IBM, Corp. 2013
+ *
+ * Authors:
+ *  Wenchao Xia   <address@hidden>
+ *
+ * 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.
+ *
+ */
+
+/* Note: This library is not thread safe yet. */
+
+#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.
+ *
+ * @p_context: used to receive the created struct.
+ */
+LIBQB_DLL_PUBLIC
+int qb_context_new(QBlockContext **p_context);
+
+/**
+ * qb_context_delete: delete context.
+ *
+ * Broker will be freed and set to NULL.
+ *
+ * @p_context: pointer to the struct pointer, *p_context will be set to NULL.
+ */
+LIBQB_DLL_PUBLIC
+void qb_context_delete(QBlockContext **p_context);
+
+/**
+ * qb_image_new: allocate a new QBlockImage struct.
+ *
+ * Subsequent qblock actions will use this struct, ref is set to 1.
+ *
+ * Returns 0 if succeed, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @p_qbi: used to receive the created struct.
+ */
+LIBQB_DLL_PUBLIC
+int qb_image_new(QBlockContext *context,
+                 QBlockImage **p_qbi);
+
+/**
+ * qb_image_ref: increase the ref of QBlockImage.
+ *
+ * @context: operation context.
+ * @p_qbi: pointer to the struct's pointer.
+ */
+LIBQB_DLL_PUBLIC
+void qb_image_ref(QBlockContext *context,
+                  QBlockImage **p_qbi);
+
+/**
+ * qb_image_unref: decrease the ref of QBlockImage.
+ *
+ * if ref is reduced to 0, p_qbi would be freed and set to NULL, at which time
+ *  if image was opened and qb_close was not called before, it would be
+ *  automatically closed.
+ *
+ * @context: operation context.
+ * @p_qbi: pointer to the struct's pointer.
+ */
+LIBQB_DLL_PUBLIC
+void qb_image_unref(QBlockContext *context,
+                    QBlockImage **p_qbi);
+
+/**
+ * qb_loc_info_new: create a new QBlockLocationInfo object.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @p_loc: pointer to receive the new created one.
+ */
+LIBQB_DLL_PUBLIC
+int qb_loc_info_new(QBlockContext *context,
+                    QBlockLocationInfo **p_loc);
+
+/**
+ * qb_loc_info_delete: free a QBlockLocationInfo.
+ *
+ * @context: operation context.
+ * @p_loc: pointer to the object, *p_loc would be set to NULL.
+ */
+LIBQB_DLL_PUBLIC
+void qb_loc_info_delete(QBlockContext *context,
+                        QBlockLocationInfo **p_loc);
+
+/**
+ * qb_fmt_info_new: create a new QBlockFormatInfo structure.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @p_fmt: pointer that will receive created struct.
+ */
+LIBQB_DLL_PUBLIC
+int qb_fmt_info_new(QBlockContext *context,
+                    QBlockFormatInfo **p_fmt);
+
+/**
+ * qb_fmt_info_delete: free QBlockFormatInfo structure.
+ *
+ * @context: operation context.
+ * @p_fmt: pointer to the struct, *p_fmt would be set to NULL.
+ */
+LIBQB_DLL_PUBLIC
+void qb_fmt_info_delete(QBlockContext *context,
+                        QBlockFormatInfo **p_fmt);
+
+
+/**
+ * qb_open: open a block object.
+ *
+ * return 0 on success, libqblock negative error value on fail.
+ *
+ * @context: operation context.
+ * @qbi: pointer to QBlockImage.
+ * @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.
+ */
+LIBQB_DLL_PUBLIC
+int qb_open(QBlockContext *context,
+            QBlockImage *qbi,
+            QBlockLocationInfo *loc,
+            QBlockFormatInfo *fmt,
+            int flag);
+
+/**
+ * qb_close: close a block object.
+ *
+ * qb_flush is automatically done inside.
+ *
+ * @context: operation context.
+ * @qbi: pointer to QBlockImage.
+ */
+LIBQB_DLL_PUBLIC
+void qb_close(QBlockContext *context,
+              QBlockImage *qbi);
+
+/**
+ * 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.
+ * @qbi: pointer to QBlockImage.
+ * @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.
+ */
+LIBQB_DLL_PUBLIC
+int qb_create(QBlockContext *context,
+              QBlockImage *qbi,
+              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.
+ * @qbi: pointer to QBlockImage.
+ * @buf: buffer that receive the content.
+ * @len: length to read.
+ * @offset: offset in the block data.
+ */
+LIBQB_DLL_PUBLIC
+int32_t qb_read(QBlockContext *context,
+                QBlockImage *qbi,
+                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.
+ * @qbi: pointer to QBlockImage.
+ * @buf: buffer that receive the content.
+ * @len: length to write.
+ * @offset: offset in the block data.
+ */
+LIBQB_DLL_PUBLIC
+int32_t qb_write(QBlockContext *context,
+                 QBlockImage *qbi,
+                 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.
+ * @qbi: pointer to QBlockImage.
+ */
+LIBQB_DLL_PUBLIC
+int qb_flush(QBlockContext *context,
+             QBlockImage *qbi);
+
+
+/* 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.
+ * @qbi: pointer to QBlockImage.
+ * @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.
+ */
+LIBQB_DLL_PUBLIC
+int qb_check_allocation(QBlockContext *context,
+                        QBlockImage *qbi,
+                        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.
+ * @qbi: pointer to QBlockImage.
+ * @p_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.
+ */
+LIBQB_DLL_PUBLIC
+int qb_info_image_static_get(QBlockContext *context,
+                             QBlockImage *qbi,
+                             QBlockStaticInfo **p_info);
+
+/**
+ * qb_delete_image_info: free image info.
+ *
+ * @context: operation context.
+ * @p_info: pointer to the information struct, *p_info will be set to NULL.
+ */
+LIBQB_DLL_PUBLIC
+void qb_info_image_static_delete(QBlockContext *context,
+                                 QBlockStaticInfo **p_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,
+ *  never return invalid value or QB_FMT_MAX.
+ *
+ * @fmt: the format string, if NULL it will return QB_FMT_NONE.
+ */
+LIBQB_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.
+ */
+LIBQB_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.
+ */
+LIBQB_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.
+ */
+LIBQB_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.
+ */
+LIBQB_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.
+ */
+LIBQB_DLL_PUBLIC
+const bool *qb_get_encrypt(const QBlockStaticInfo *info);
+#endif
-- 
1.7.1