From patchwork Fri Nov 30 06:17:21 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Wayne Xia X-Patchwork-Id: 202885 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 B566B2C0097 for ; Fri, 30 Nov 2012 18:06:44 +1100 (EST) Received: from localhost ([::1]:52869 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TeJx8-0008Up-AE for incoming@patchwork.ozlabs.org; Fri, 30 Nov 2012 01:19:58 -0500 Received: from eggs.gnu.org ([208.118.235.92]:37387) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TeJwa-0007El-ED for qemu-devel@nongnu.org; Fri, 30 Nov 2012 01:19:27 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TeJwV-0002yh-O3 for qemu-devel@nongnu.org; Fri, 30 Nov 2012 01:19:24 -0500 Received: from e28smtp07.in.ibm.com ([122.248.162.7]:48749) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TeJwU-0002uw-Sw for qemu-devel@nongnu.org; Fri, 30 Nov 2012 01:19:19 -0500 Received: from /spool/local by e28smtp07.in.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Fri, 30 Nov 2012 11:49:17 +0530 Received: from d28relay02.in.ibm.com (9.184.220.59) by e28smtp07.in.ibm.com (192.168.1.137) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Fri, 30 Nov 2012 11:49:15 +0530 Received: from d28av01.in.ibm.com (d28av01.in.ibm.com [9.184.220.63]) by d28relay02.in.ibm.com (8.13.8/8.13.8/NCO v10.0) with ESMTP id qAU6JDVU27000842 for ; Fri, 30 Nov 2012 11:49:13 +0530 Received: from d28av01.in.ibm.com (loopback [127.0.0.1]) by d28av01.in.ibm.com (8.14.4/8.13.1/NCO v10.0 AVout) with ESMTP id qAUBn5MH012556 for ; Fri, 30 Nov 2012 11:49:05 GMT Received: from RedHat62GAWSWenchao (wenchaox.cn.ibm.com [9.115.122.172]) by d28av01.in.ibm.com (8.14.4/8.13.1/NCO v10.0 AVin) with ESMTP id qAUBlMqM004902; Fri, 30 Nov 2012 11:49:04 GMT From: Wenchao Xia To: qemu-devel@nongnu.org Date: Fri, 30 Nov 2012 14:17:21 +0800 Message-Id: <1354256243-8375-6-git-send-email-xiawenc@linux.vnet.ibm.com> X-Mailer: git-send-email 1.7.1 In-Reply-To: <1354256243-8375-1-git-send-email-xiawenc@linux.vnet.ibm.com> References: <1354256243-8375-1-git-send-email-xiawenc@linux.vnet.ibm.com> x-cbid: 12113006-8878-0000-0000-000004FC6A94 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 122.248.162.7 Cc: kwolf@redhat.com, aliguori@us.ibm.com, stefanha@gmail.com, blauwirbel@gmail.com, pbonzini@redhat.com, Wenchao Xia Subject: [Qemu-devel] [PATCH v13 5/7] 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, libqblock-aio.h. For ABI some reserved bytes are used in structure defines. v11: Moved API design into this patch. Added libqblock-aio.h, which contain aio internal function prototype, although it is not implemented yet. Added doc about thread not safe in libqblock.h. Moved including of block_int.h from libqblock.h to libqblock.c Spell fix. Use g_malloc0_n instead of g_malloc0. Renamed FUNC_CLEAN to QB_CLEAN, removed unused macros, use glib function directly, for malloc, free and strdup. v12: Changed QBlockImage new/delete API to new/ref/unref. Signed-off-by: Wenchao Xia --- libqblock/libqblock-aio.h | 8 + libqblock/libqblock-error.h | 49 ++++++ libqblock/libqblock-internal.h | 68 ++++++++ libqblock/libqblock-types.h | 245 +++++++++++++++++++++++++++ libqblock/libqblock.h | 356 +++++++++++++++++++++++++++++++++++++++- 5 files changed, 725 insertions(+), 1 deletions(-) create mode 100644 libqblock/libqblock-aio.h create mode 100644 libqblock/libqblock-internal.h diff --git a/libqblock/libqblock-aio.h b/libqblock/libqblock-aio.h new file mode 100644 index 0000000..2d699ae --- /dev/null +++ b/libqblock/libqblock-aio.h @@ -0,0 +1,8 @@ +#ifndef LIBQBLOCK_AIO_H +#define LIBQBLOCK_AIO_H + +/* This function initialize lower block system at runtime, should be called + once before any real block operation. */ +void libqblock_runtime_init(void); + +#endif diff --git a/libqblock/libqblock-error.h b/libqblock/libqblock-error.h index e69de29..4ffd1f1 100644 --- a/libqblock/libqblock-error.h +++ b/libqblock/libqblock-error.h @@ -0,0 +1,49 @@ +/* + * QEMU block layer library + * + * Copyright IBM, Corp. 2012 + * + * Authors: + * Wenchao Xia + * + * 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-internal.h b/libqblock/libqblock-internal.h new file mode 100644 index 0000000..93f24d9 --- /dev/null +++ b/libqblock/libqblock-internal.h @@ -0,0 +1,68 @@ +/* + * QEMU block layer library + * + * Copyright IBM, Corp. 2012 + * + * Authors: + * Wenchao Xia + * + * This work is licensed under the terms of the GNU LGPL, version 2 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +#ifndef LIBQBLOCK_INTERNAL +#define LIBQBLOCK_INTERNAL + +#include + +#include "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..4352bf2 100644 --- a/libqblock/libqblock-types.h +++ b/libqblock/libqblock-types.h @@ -0,0 +1,245 @@ +/* + * QEMU block layer library + * + * Copyright IBM, Corp. 2012 + * + * Authors: + * Wenchao Xia + * + * This work is licensed under the terms of the GNU LGPL, version 2 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +#ifndef LIBQBLOCK_TYPES_H +#define LIBQBLOCK_TYPES_H + +#include +#include +#include + +#if defined(__GNUC__) && __GNUC__ >= 4 + #ifdef LIBQB_BUILD + #define DLL_PUBLIC __attribute__((visibility("default"))) + #else + #define 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/8]; + }; +} 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 verion 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. + * @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; + uint64_t reserved[QBLOCK_FMT_OPTIONS_UNION_SIZE/8]; + }; +} 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 b0f9daf..685f8f3 100644 --- a/libqblock/libqblock.h +++ b/libqblock/libqblock.h @@ -1 +1,355 @@ -__attribute__((visibility("default"))) int libqb_test(void); +/* + * QEMU block layer library + * + * Copyright IBM, Corp. 2012 + * + * Authors: + * Wenchao Xia + * + * This work is licensed under the terms of the GNU LGPL, version 2 or later. + * See the COPYING.LIB file in the top-level directory. + * + */ + +/* 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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +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. + */ +DLL_PUBLIC +QBlockFormat qb_str2fmttype(const char *fmt_str); + +/** + * qb_fmttype2str: translate libqblock format enum type to a string. + * + * return a pointer to the string, or NULL if type is not supported, and + * returned pointer must NOT be freed. + * + * @fmt: the format enum type. + */ +DLL_PUBLIC +const char *qb_fmttype2str(QBlockFormat fmt_type); + +/** + * qb_loc_info_dup: duplicate a QBlockLocationInfo instance. + * + * return a pointer to new allocated one having the same values with input, + * it need to be freed by qb_loc_info_delete later. Never fail except OOM. + * + * @loc: pointer to the source instance. + */ +DLL_PUBLIC +QBlockLocationInfo *qb_loc_info_dup(const QBlockLocationInfo *loc); + +/** + * qb_get_virt_size: get virtual size. + * + * return a pointer, which pointer to a member in info, or NULL if info is + * not valid. + * + * @info: pointer to the QBlockStaticInfo structure. + */ +DLL_PUBLIC +const uint64_t *qb_get_virt_size(const QBlockStaticInfo *info); + +/** + * qb_get_backing_loc: get backing file location. + * + * return a pointer, which pointer to a member in info, or NULL if info is + * not valid, or image have no such property. + * + * @info: pointer to the QBlockStaticInfo structure. + */ +DLL_PUBLIC +const QBlockLocationInfo *qb_get_backing_loc(const QBlockStaticInfo *info); + +/** + * qb_get_encrypt: get encrytion flag. + * + * return a pointer, which pointer to a member in info, or NULL if info is + * not valid, or image have no such property. + * + * @info: pointer to the QBlockStaticInfo structure. + */ +DLL_PUBLIC +const bool *qb_get_encrypt(const QBlockStaticInfo *info); +#endif