[libvirt] [PATCH 1/5] define interface with vbox_common

[Michal Privoznik]

On 23.06.2014 06:25, Taowei wrote:
> The vboxGlobalData and the vboxUniformedAPI is defined here. It defines
> the middle layer interface. When using this file, it needs a context
> to explain how *.c files treat vbox structs in vboxGlobalData(vboxObj,
> vboxSession and so on). See annotate in this file.
>
> ---
>   src/vbox/vbox_common.h |  108 ++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 108 insertions(+)
>   create mode 100644 src/vbox/vbox_common.h

Introducing a new file should be followed by Makefile.am change not a 
separate patch like 5/5.

>
> diff --git a/src/vbox/vbox_common.h b/src/vbox/vbox_common.h
> new file mode 100644
> index 0000000..eba360e
> --- /dev/null
> +++ b/src/vbox/vbox_common.h
> @@ -0,0 +1,108 @@
> +/*
> + * Copyright 2014, Taowei Luo (uaedante at gmail.com)
> + *
> + * This library is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU Lesser General Public
> + * License as published by the Free Software Foundation; either
> + * version 2.1 of the License, or (at your option) any later version.
> + *
> + * This library is distributed in the hope that it will be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> + * Lesser General Public License for more details.
> + *
> + * You should have received a copy of the GNU Lesser General Public
> + * License along with this library.  If not, see
> + * <http://www.gnu.org/licenses/>.
> + */
> +
> +#include "internal.h"
> +
> +/* This file may be used in three place. That is vbox_tmpl.c,
> + * vbox_common.c and vbox_driver.c. Two important things is defined
> + * here, which is vboxGlobalData and vboxUniformedAPI.
> + *
> + * The vbox_tmpl.c is the only place where the driver knows the inside
> + * architecture of those vbox structs(vboxObj, vboxSession,
> + * pFuncs, vboxCallback and vboxQueue). The file should be included
> + * after the currect vbox_CAPI_v*.h, then we can use the vbox structs
> + * in vboxGlobalData. The vbox_tmpl.c should implement functions
> + * defined in vboxUniformedAPI.
> + *
> + * In vbox_driver.c, it is used to define the struct vboxUniformedAPI.
> + * The vbox_driver.c collects vboxUniformedAPI for all versions.
> + * Then vboxRegister calls the vboxRegisterUniformedAPI to register.
> + * Note: In vbox_driver.c, the vbox structs in vboxGlobalData is
> + * defined by vbox_CAPI_v2.2.h.
> + *
> + * The vbox_common.c, it is used to generate common codes for all vbox
> + * versions. Bacause the same member varible's offset in a vbox struct
> + * may change between different vbox versions. The vbox_common.c
> + * shouldn't directly use struct's member varibles defined in
> + * vbox_CAPI_v*.h. To make things safety, we include the
> + * vbox_commondef.h in vbox_common.c. In this case, we treat structs
> + * defined by vbox as a void*. The common codes don't concern about
> + * the inside of this structs(actually, we can't, in the common level).
> + * With the help of vboxUniformed API, we call VirtualBox's API and
> + * implement the vbox driver in a high level.
> + *
> + * In conclusion:
> + *  * In vbox_tmpl.c, this file is included after vbox_CAPI_v*.h
> + *  * In vbox_driver.c, this file is included after vbox_glue.h
> + *  * In vbox_common.c, this file is included after vbox_commondef.h
> + *
> + */
> +
> +typedef struct {
> +    virMutex lock;
> +    unsigned long version;
> +
> +    virCapsPtr caps;
> +    virDomainXMLOptionPtr xmlopt;
> +
> +    IVirtualBox *vboxObj;
> +    ISession *vboxSession;
> +
> +    /** Our version specific API table pointer. */
> +    PCVBOXXPCOM pFuncs;
> +
> +    /* The next is used when VBOX_API_VERSION > 2002000 */
> +    /* Async event handling */
> +    virObjectEventStatePtr domainEvents;
> +    int fdWatch;
> +# if VBOX_API_VERSION > 2002000 && VBOX_API_VERSION <= 3002000
> +    /* IVirtualBoxCallback is used in VirtualBox 3.x only */
> +    IVirtualBoxCallback *vboxCallback;
> +# else /* VBOX_API_VERSION > 2002000 && VBOX_API_VERSION <= 3002000 */
> +    void *vboxCallback;
> +# endif /* VBOX_API_VERSION > 2002000 && VBOX_API_VERSION <= 3002000 */
> +
> +# if VBOX_API_VERSION > 2002000
> +    nsIEventQueue  *vboxQueue;
> +# else /* VBOX_API_VERSION == 2002000 or undefined */
> +    void *vboxQueue;
> +# endif /* VBOX_API_VERSION == 2002000 or undefined */

Consider installing ccpi to catch errors like these. We are not in a 
ifdef block, so there's no need to put a space in between hash and if.

> +    int volatile vboxCallBackRefCount;
> +
> +    /* pointer back to the connection */
> +    virConnectPtr conn;
> +
> +} vboxGlobalData;
> +
> +/* vboxUniformedAPI gives vbox_common.c a uniformed layer to see
> + * vbox API.
> + */
> +typedef struct {
> +    /* vbox API version */
> +    uint32_t uVersion;
> +    /* vbox APIs */
> +    int (*pfnInitialize)(vboxGlobalData *data);
> +    int (*initializeFWatch)(vboxGlobalData *data);
> +    /* vbox API features */
> +    bool fWatchNeedInitialize;
> +} vboxUniformedAPI;
> +
> +/* Register the vboxUniformedAPI based on the current vbox version */
> +void vboxRegisterUniformedAPI(vboxUniformedAPI *vboxAPI);
> +
> +int vboxInitialize(vboxGlobalData *data);
>