From patchwork Wed Feb 27 03:10:15 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Wayne Xia X-Patchwork-Id: 223496 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 1EB522C0297 for ; Wed, 27 Feb 2013 15:06:49 +1100 (EST) Received: from localhost ([::1]:33997 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UAXSE-0000qL-Bd for incoming@patchwork.ozlabs.org; Tue, 26 Feb 2013 22:13:14 -0500 Received: from eggs.gnu.org ([208.118.235.92]:41858) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UAXRO-0007w1-8B for qemu-devel@nongnu.org; Tue, 26 Feb 2013 22:12:24 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UAXRJ-0006LW-IH for qemu-devel@nongnu.org; Tue, 26 Feb 2013 22:12:22 -0500 Received: from e28smtp08.in.ibm.com ([122.248.162.8]:40561) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UAXRI-0006Kn-Gu for qemu-devel@nongnu.org; Tue, 26 Feb 2013 22:12:17 -0500 Received: from /spool/local by e28smtp08.in.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Wed, 27 Feb 2013 08:38:33 +0530 Received: from d28dlp02.in.ibm.com (9.184.220.127) by e28smtp08.in.ibm.com (192.168.1.138) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Wed, 27 Feb 2013 08:38:32 +0530 Received: from d28relay01.in.ibm.com (d28relay01.in.ibm.com [9.184.220.58]) by d28dlp02.in.ibm.com (Postfix) with ESMTP id 8951C394002D for ; Wed, 27 Feb 2013 08:42:12 +0530 (IST) Received: from d28av05.in.ibm.com (d28av05.in.ibm.com [9.184.220.67]) by d28relay01.in.ibm.com (8.13.8/8.13.8/NCO v10.0) with ESMTP id r1R3C8pg31457374 for ; Wed, 27 Feb 2013 08:42:08 +0530 Received: from d28av05.in.ibm.com (loopback [127.0.0.1]) by d28av05.in.ibm.com (8.14.4/8.13.1/NCO v10.0 AVout) with ESMTP id r1R3CCPG025462 for ; Wed, 27 Feb 2013 14:12:12 +1100 Received: from RH63Wenchao (wenchaox.cn.ibm.com [9.115.122.44]) by d28av05.in.ibm.com (8.14.4/8.13.1/NCO v10.0 AVin) with ESMTP id r1R3A7fc018808; Wed, 27 Feb 2013 14:12:11 +1100 From: Wenchao Xia To: qemu-devel@nongnu.org Date: Wed, 27 Feb 2013 11:10:15 +0800 Message-Id: <1361934618-32026-8-git-send-email-xiawenc@linux.vnet.ibm.com> X-Mailer: git-send-email 1.7.1 In-Reply-To: <1361934618-32026-1-git-send-email-xiawenc@linux.vnet.ibm.com> References: <1361934618-32026-1-git-send-email-xiawenc@linux.vnet.ibm.com> X-Content-Scanned: Fidelis XPS MAILER x-cbid: 13022703-2000-0000-0000-00000B19338A X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 122.248.162.8 Cc: kwolf@redhat.com, aliguori@us.ibm.com, stefanha@gmail.com, pbonzini@redhat.com, Wenchao Xia Subject: [Qemu-devel] [PATCH V20 07/10] libqblock: libqblock API design and type defines X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org 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 QEMU_DLL_PUBLIC is used to mark exported function. Important APIs: 1 QBlockImage. It stands for an block image object. 2 QBlockStaticInfo. It contains static information such as location, backing file, size. 3 Sync I/O. It is similar to C file open, read, write and close operations. Signed-off-by: Wenchao Xia --- libqblock/libqblock-error.h | 35 ++++++ libqblock/libqblock-internal.h | 62 ++++++++++ libqblock/libqblock-types.h | 264 ++++++++++++++++++++++++++++++++++++++++ libqblock/libqblock.h | 243 ++++++++++++++++++++++++++++++++++++ 4 files changed, 604 insertions(+), 0 deletions(-) create mode 100644 libqblock/libqblock-internal.h diff --git a/libqblock/libqblock-error.h b/libqblock/libqblock-error.h index e69de29..967f2e0 100644 --- a/libqblock/libqblock-error.h +++ b/libqblock/libqblock-error.h @@ -0,0 +1,35 @@ +/* + * QEMU block layer library + * + * Copyright IBM, Corp. 2013 + * + * Authors: + * Wenchao Xia + * + * This work is licensed under the terms of the GNU LGPL, version 2 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +#ifndef LIBQBLOCK_ERROR +#define LIBQBLOCK_ERROR + +#include "libqblock-types.h" + +#define QB_ERR_INTERNAL_ERR (-1) +#define QB_ERR_FATAL_ERR (-2) +#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, caller must free it later. + * + * @image: the image opened, must not be NULL. + */ +QEMU_DLL_PUBLIC +char *qb_error_get_human_str(QBlockImage *image); + +#endif diff --git a/libqblock/libqblock-internal.h b/libqblock/libqblock-internal.h new file mode 100644 index 0000000..d09f9c1 --- /dev/null +++ b/libqblock/libqblock-internal.h @@ -0,0 +1,62 @@ +/* + * QEMU block layer library + * + * Copyright IBM, Corp. 2013 + * + * Authors: + * Wenchao Xia + * + * This work is licensed under the terms of the GNU LGPL, version 2 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +#ifndef LIBQBLOCK_INTERNAL +#define LIBQBLOCK_INTERNAL + +#include + +#include "block/block.h" +#include "libqblock-types.h" + +/* this file contains defines and types used inside the library. */ + +typedef 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 */ +} QBlockContext; + +/* 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; + QBlockContext *ctx; +}; + +/** + * 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; + +static inline GQuark qb_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..3e79447 100644 --- a/libqblock/libqblock-types.h +++ b/libqblock/libqblock-types.h @@ -0,0 +1,264 @@ +/* + * QEMU block layer library + * + * Copyright IBM, Corp. 2013 + * + * Authors: + * Wenchao Xia + * + * This work is licensed under the terms of the GNU LGPL, version 2 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +#ifndef LIBQBLOCK_TYPES_H +#define LIBQBLOCK_TYPES_H + +#include +#include +#include + +/* + * In case libqblock is used by other project which have not defined + * QEMU_DLL_PUBLIC. + */ +#ifndef QEMU_DLL_PUBLIC +#define QEMU_DLL_PUBLIC +#endif + +typedef void (*QBlockReserved)(void); +#define LIBQBLOCK_RESERVED_SIZE (128/sizeof(QBlockReserved)) + +/* this library is designed around this core struct. */ +typedef struct QBlockImage QBlockImage; + +/* 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 + +/* + * The host page cache is always used. + * Flush operations are required to ensure writes reach the disk. + */ +#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 { + /* in information retrieving function it will receive an allocated string, + which need to be freed later, so can't be const. */ + char *filename; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} 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 / sizeof(QBlockReserved)) +typedef struct QBlockLocationInfo { + QBlockProtocol prot_type; + union { + QBlockProtocolOptionsFile o_file; + QBlockReserved union_reserved[QBLOCK_PROT_OPTIONS_UNION_SIZE]; + }; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockLocationInfo; + + +/* format related options */ +typedef enum QBlockFormat { + QB_FORMAT_NONE = 0, + QB_FORMAT_COW, + QB_FORMAT_QED, + QB_FORMAT_QCOW, + QB_FORMAT_QCOW2, + QB_FORMAT_RAW, + QB_FORMAT_RBD, + QB_FORMAT_SHEEPDOG, + QB_FORMAT_VDI, + QB_FORMAT_VMDK, + QB_FORMAT_VPC, + QB_FORMAT_MAX +} QBlockFormat; + +typedef struct QBlockFormatOptionsCOW { + QBlockLocationInfo backing_loc; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatOptionsCOW; + +typedef struct QBlockFormatOptionsQED { + QBlockLocationInfo backing_loc; + QBlockFormat backing_fmt; + uint64_t cluster_size; /* unit is bytes */ + uint64_t table_size; /* unit is clusters */ + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatOptionsQED; + +typedef struct QBlockFormatOptionsQCOW { + QBlockLocationInfo backing_loc; + bool encrypt; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatOptionsQCOW; + +/* "Compatibility level (0.10 or 1.1)" */ +typedef enum QBlockFormatOptionsQCOW2CompatLv { + QB_FORMAT_QCOW2_COMPAT_DEFAULT = 0, + QB_FORMAT_QCOW2_COMPAT_V0_10, + QB_FORMAT_QCOW2_COMPAT_V1_10, +} QBlockFormatOptionsQCOW2CompatLv; + +/* off or metadata */ +typedef enum QBlockFormatOptionsQCOW2PreAlloc { + QB_FORMAT_QCOW2_PREALLOC_DEFAULT = 0, + QB_FORMAT_QCOW2_PREALLOC_OFF, + QB_FORMAT_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; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatOptionsQCOW2; + +typedef struct QBlockFormatOptionsRAW { + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatOptionsRAW; + +typedef struct QBlockFormatOptionsRBD { + uint64_t cluster_size; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatOptionsRBD; + +/* off or full */ +typedef enum QBlockFormatOptionsSDPreAlloc { + QB_FORMAT_SD_PREALLOC_DEFAULT = 0, + QB_FORMAT_SD_PREALLOC_OFF, + QB_FORMAT_SD_PREALLOC_FULL, +} QBlockFormatOptionsSDPreAlloc; + +typedef struct QBlockFormatOptionsSD { + QBlockLocationInfo backing_loc; + QBlockFormatOptionsSDPreAlloc pre_mode; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatOptionsSD; + +typedef enum QBlockFormatOptionsVDIPreAlloc { + QB_FORMAT_VDI_PREALLOC_DEFAULT = 0, + QB_FORMAT_VDI_PREALLOC_OFF, + QB_FORMAT_VDI_PREALLOC_METADATA, +} QBlockFormatOptionsVDIPreAlloc; + +typedef struct QBlockFormatOptionsVDI { + uint64_t cluster_size; + QBlockFormatOptionsVDIPreAlloc pre_mode; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatOptionsVDI; + +/* whether compact to vmdk version 6 */ +typedef enum QBlockFormatOptionsVMDKCompatLv { + QB_FORMAT_VMDK_COMPAT_DEFAULT = 0, + QB_FORMAT_VMDK_COMPAT_VMDKV6_FALSE, + QB_FORMAT_VMDK_COMPAT_VMDKV6_TRUE, +} QBlockFormatOptionsVMDKCompatLv; + +/* vmdk flat extent format, values: +"{monolithicSparse (default) | monolithicFlat | twoGbMaxExtentSparse | +twoGbMaxExtentFlat | streamOptimized} */ +typedef enum QBlockFormatOptionsVMDKSubfmt { + QB_FORMAT_VMDK_SUBFMT_DEFAULT = 0, + QB_FORMAT_VMDK_SUBFMT_MONOLITHIC_SPARSE, + QB_FORMAT_VMDK_SUBFMT_MONOLITHIC_FLAT, + QB_FORMAT_VMDK_SUBFMT_TWOGBMAX_EXTENT_SPARSE, + QB_FORMAT_VMDK_SUBFMT_TWOGBMAX_EXTENT_FLAT, + QB_FORMAT_VMDK_SUBFMT_STREAM_OPTIMIZED, +} QBlockFormatOptionsVMDKSubfmt; + +typedef struct QBlockFormatOptionsVMDK { + QBlockLocationInfo backing_loc; + QBlockFormatOptionsVMDKCompatLv cpt_lv; + QBlockFormatOptionsVMDKSubfmt subfmt; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatOptionsVMDK; + +/* "{dynamic (default) | fixed} " */ +typedef enum QBlockFormatOptionsVPCSubfmt { + QB_FORMAT_VPC_SUBFMT_DEFAULT = 0, + QB_FORMAT_VPC_SUBFMT_DYNAMIC, + QB_FORMAT_VPC_SUBFMT_FIXED, +} QBlockFormatOptionsVPCSubfmt; + +typedef struct QBlockFormatOptionsVPC { + QBlockFormatOptionsVPCSubfmt subfmt; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} 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. + * @o_cow~@o_vdi: 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; + QBlockReserved union_reserved[QBLOCK_FMT_OPTIONS_UNION_SIZE]; + }; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockFormatInfo; + +/** + * QBlockStaticInfo: information about the block image. + * + * @loc: location information. + * @fmt: format information. + * @sector_size: how many bytes in a sector. + */ +typedef struct QBlockStaticInfo { + QBlockLocationInfo loc; + QBlockFormatInfo fmt; + int sector_size; + QBlockReserved reserved[LIBQBLOCK_RESERVED_SIZE]; +} QBlockStaticInfo; + + +#endif diff --git a/libqblock/libqblock.h b/libqblock/libqblock.h index e69de29..755e44c 100644 --- a/libqblock/libqblock.h +++ b/libqblock/libqblock.h @@ -0,0 +1,243 @@ +/* + * QEMU block layer library + * + * Copyright IBM, Corp. 2013 + * + * Authors: + * Wenchao Xia + * + * This work is licensed under the terms of the GNU LGPL, version 2 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +/* Note: This library is not thread safe yet. */ + +#ifndef LIBQBLOCK_H +#define LIBQBLOCK_H + +#include "libqblock-types.h" +#include "libqblock-error.h" + +/** + * 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, if fail call + * qb_image_unref() to free it. + * + * @p_qbi: used to receive the created struct. + */ +QEMU_DLL_PUBLIC +int qb_image_new(QBlockImage **p_qbi); + +/** + * qb_image_ref: increase the ref of QBlockImage. + * + * @qbi: pointer to the image structure. + */ +QEMU_DLL_PUBLIC +void qb_image_ref(QBlockImage *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. + * + * @p_qbi: pointer to the struct's pointer. + */ +QEMU_DLL_PUBLIC +void qb_image_unref(QBlockImage **p_qbi); + +/** + * qb_open: open a block object. + * + * return 0 on success, libqblock negative error value on fail. + * + * @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. + */ +QEMU_DLL_PUBLIC +int qb_open(QBlockImage *qbi, + QBlockLocationInfo *loc, + QBlockFormatInfo *fmt, + int flag); + +/** + * qb_close: close a block object. + * + * qb_flush is automatically done inside. + * + * @qbi: pointer to QBlockImage. + */ +QEMU_DLL_PUBLIC +void qb_close(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. + * + * @qbi: pointer to QBlockImage, used to get error message. + * @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, it is used if + * backing file need to be opened. + */ +QEMU_DLL_PUBLIC +int qb_create(QBlockImage *qbi, + QBlockLocationInfo *loc, + QBlockFormatInfo *fmt, + int flag); + + +/* sync access */ +/** + * qb_read: block sync read. + * + * return 0 on success, libqblock negative error value on fail. + * + * @qbi: pointer to QBlockImage. + * @buf: buffer that receive the content. + * @len: length to read. + * @offset: offset in the block data. + */ +QEMU_DLL_PUBLIC +int32_t qb_read(QBlockImage *qbi, + uint8_t *buf, + uint32_t len, + uint64_t offset); + +/** + * qb_write: block sync write. + * + * return 0 on success, libqblock negative error value on fail. + * + * @qbi: pointer to QBlockImage. + * @buf: buffer that receive the content. + * @len: length to write. + * @offset: offset in the block data. + */ +QEMU_DLL_PUBLIC +int32_t qb_write(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. + * + * @qbi: pointer to QBlockImage. + */ +QEMU_DLL_PUBLIC +int qb_flush(QBlockImage *qbi); + + +/* advance image APIs */ +/** + * qb_check_allocation: check if [start, start+length-1] was allocated on the + * image. + * + * return 0 on success, libqblock negative error value on fail. + * + * @qbi: pointer to QBlockImage. + * @start: start position, unit is byte. + * @length: length to check, unit is byte. + * @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. + * + */ +QEMU_DLL_PUBLIC +int qb_check_allocation(QBlockImage *qbi, + uint64_t start, + uint64_t length, + int *pstatus, + uint64_t *plength); + +/* image information */ +/** + * qb_get_image_info: get image info. + * + * return 0 on success, libqblock negative error value on fail. + * + * @qbi: pointer to QBlockImage. + * @info: pointer that would receive the information. + * + * all char* in info must be freed later by g_free(). + */ +QEMU_DLL_PUBLIC +int qb_info_image_static_get(QBlockImage *qbi, + QBlockStaticInfo *info); + +/* helper functions */ +/** + * qb_str2fmttype: translate format string to libqblock format enum type. + * + * return the type, or QB_FORMAT_NONE if string matches none of supported types, + * never return invalid value or QB_FORMAT_MAX. + * + * @fmt: the format string, if NULL it will return QB_FORMAT_NONE. + */ +QEMU_DLL_PUBLIC +QBlockFormat qb_str2fmttype(const char *fmt_str); + +/** + * qb_formattype2str: 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. + */ +QEMU_DLL_PUBLIC +const char *qb_formattype2str(QBlockFormat fmt_type); + +/** + * 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. + */ +QEMU_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. + */ +QEMU_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. + */ +QEMU_DLL_PUBLIC +const bool *qb_get_encrypt(const QBlockStaticInfo *info); +#endif