include/VBox/pdmthread.h

	pdmthread.h revision 7b067f3f07310bff46d1d6a4ac94d8b9bb7ccccd
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync/** @file
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * PDM - Pluggable Device Manager, Threads. (VMM)
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync/*
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync *
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * available from http://www.virtualbox.org. This file is free software;
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * you can redistribute it and/or modify it under the terms of the GNU
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * General Public License (GPL) as published by the Free Software
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync *
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * The contents of this file may alternatively be used under the terms
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * of the Common Development and Distribution License Version 1.0
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * VirtualBox OSE distribution, in which case the provisions of the
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * CDDL are applicable instead of those of the GPL.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync *
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * You may elect to license modified versions of this file under the
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * terms and conditions of either the GPL or the CDDL or both.
3d40f685fa5cdd9cb665ae3cbf5f76113dafcb99vboxsync *
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * additional information or have any questions.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync#ifndef ___VBox_pdmthread_h
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync#define ___VBox_pdmthread_h
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync#include <VBox/cdefs.h>
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync#include <VBox/types.h>
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync#ifdef IN_RING3
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync# include <iprt/thread.h>
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync#endif
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsyncRT_C_DECLS_BEGIN
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync/** @defgroup grp_pdm_thread    The PDM Threads API
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * @ingroup grp_pdm
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * @{
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync */
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync/**
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * The thread state
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsynctypedef enum PDMTHREADSTATE
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync{
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    /** The usual invalid 0 entry. */
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync    PDMTHREADSTATE_INVALID = 0,
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    /** The thread is initializing.
81db31727ed27322c3f5e3bc40e71fe7fc54bf91vboxsync     * Prev state: none
81db31727ed27322c3f5e3bc40e71fe7fc54bf91vboxsync     * Next state: suspended, terminating (error) */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    PDMTHREADSTATE_INITIALIZING,
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    /** The thread has been asked to suspend.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Prev state: running
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Next state: suspended */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    PDMTHREADSTATE_SUSPENDING,
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    /** The thread is supended.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Prev state: suspending, initializing
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Next state: resuming, terminated. */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    PDMTHREADSTATE_SUSPENDED,
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    /** The thread is active.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Prev state: suspended
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Next state: running, terminating. */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    PDMTHREADSTATE_RESUMING,
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    /** The thread is active.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Prev state: resuming
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Next state: suspending, terminating. */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    PDMTHREADSTATE_RUNNING,
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    /** The thread has been asked to terminate.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Prev state: initializing, suspended, resuming, running
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Next state: terminated. */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    PDMTHREADSTATE_TERMINATING,
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync    /** The thread is terminating / has terminated.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync     * Prev state: terminating
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync     * Next state: none */
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync    PDMTHREADSTATE_TERMINATED,
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync    /** The usual 32-bit hack. */
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync    PDMTHREADSTATE_32BIT_HACK = 0x7fffffff
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync} PDMTHREADSTATE;
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync/** A pointer to a PDM thread. */
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsynctypedef R3PTRTYPE(struct PDMTHREAD *) PPDMTHREAD;
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync/** A pointer to a pointer to a PDM thread. */
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsynctypedef PPDMTHREAD *PPPDMTHREAD;
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync/**
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * PDM thread, device variation.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync *
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * @returns VBox status code.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * @param   pDevIns     The device instance.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * @param   pThread     The PDM thread data.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync */
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsynctypedef int FNPDMTHREADDEV(PPDMDEVINS pDevIns, PPDMTHREAD pThread);
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync/** Pointer to a FNPDMTHREADDEV(). */
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsynctypedef FNPDMTHREADDEV *PFNPDMTHREADDEV;
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync/**
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * PDM thread, USB device variation.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync *
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * @returns VBox status code.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * @param   pUsbIns     The USB device instance.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync * @param   pThread     The PDM thread data.
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsynctypedef int FNPDMTHREADUSB(PPDMUSBINS pUsbIns, PPDMTHREAD pThread);
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync/** Pointer to a FNPDMTHREADUSB(). */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsynctypedef FNPDMTHREADUSB *PFNPDMTHREADUSB;
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync/**
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * PDM thread, driver variation.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync *
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * @returns VBox status code.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * @param   pDrvIns     The driver instance.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * @param   pThread     The PDM thread data.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsynctypedef int FNPDMTHREADDRV(PPDMDRVINS pDrvIns, PPDMTHREAD pThread);
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync/** Pointer to a FNPDMTHREADDRV(). */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsynctypedef FNPDMTHREADDRV *PFNPDMTHREADDRV;
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync/**
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * PDM thread, driver variation.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync *
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * @returns VBox status code.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * @param   pVM         The VM handle.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * @param   pThread     The PDM thread data.
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync */
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsynctypedef int FNPDMTHREADINT(PVM pVM, PPDMTHREAD pThread);
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync/** Pointer to a FNPDMTHREADINT(). */
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsynctypedef FNPDMTHREADINT *PFNPDMTHREADINT;
cec22f4b94382f5ebee9d2f6b6df672689681e07vboxsync
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync/**
4c37c32b924cb13b821f9d2e01f42cabbd3d9cf9vboxsync * PDM thread, driver variation.
 *
 * @returns VBox status code.
 * @param   pThread     The PDM thread data.
 */
typedef int FNPDMTHREADEXT(PPDMTHREAD pThread);
/** Pointer to a FNPDMTHREADEXT(). */
typedef FNPDMTHREADEXT *PFNPDMTHREADEXT;


/**
 * PDM thread wakeup call, device variation.
 *
 * @returns VBox status code.
 * @param   pDevIns     The device instance.
 * @param   pThread     The PDM thread data.
 */
typedef int FNPDMTHREADWAKEUPDEV(PPDMDEVINS pDevIns, PPDMTHREAD pThread);
/** Pointer to a FNPDMTHREADDEV(). */
typedef FNPDMTHREADWAKEUPDEV *PFNPDMTHREADWAKEUPDEV;

/**
 * PDM thread wakeup call, device variation.
 *
 * @returns VBox status code.
 * @param   pUsbIns     The USB device instance.
 * @param   pThread     The PDM thread data.
 */
typedef int FNPDMTHREADWAKEUPUSB(PPDMUSBINS pUsbIns, PPDMTHREAD pThread);
/** Pointer to a FNPDMTHREADUSB(). */
typedef FNPDMTHREADWAKEUPUSB *PFNPDMTHREADWAKEUPUSB;

/**
 * PDM thread wakeup call, driver variation.
 *
 * @returns VBox status code.
 * @param   pDrvIns     The driver instance.
 * @param   pThread     The PDM thread data.
 */
typedef int FNPDMTHREADWAKEUPDRV(PPDMDRVINS pDrvIns, PPDMTHREAD pThread);
/** Pointer to a FNPDMTHREADDRV(). */
typedef FNPDMTHREADWAKEUPDRV *PFNPDMTHREADWAKEUPDRV;

/**
 * PDM thread wakeup call, internal variation.
 *
 * @returns VBox status code.
 * @param   pVM         The VM handle.
 * @param   pThread     The PDM thread data.
 */
typedef int FNPDMTHREADWAKEUPINT(PVM pVM, PPDMTHREAD pThread);
/** Pointer to a FNPDMTHREADWAKEUPINT(). */
typedef FNPDMTHREADWAKEUPINT *PFNPDMTHREADWAKEUPINT;

/**
 * PDM thread wakeup call, external variation.
 *
 * @returns VBox status code.
 * @param   pThread     The PDM thread data.
 */
typedef int FNPDMTHREADWAKEUPEXT(PPDMTHREAD pThread);
/** Pointer to a FNPDMTHREADEXT(). */
typedef FNPDMTHREADWAKEUPEXT *PFNPDMTHREADWAKEUPEXT;


/**
 * PDM Thread instance data.
 */
typedef struct PDMTHREAD
{
    /** PDMTHREAD_VERSION. */
    uint32_t                    u32Version;
    /** The thread state. */
    PDMTHREADSTATE volatile     enmState;
    /** The thread handle. */
    RTTHREAD                    Thread;
    /** The user parameter. */
    R3PTRTYPE(void *)           pvUser;
    /** Data specific to the kind of thread.
     * This should really be in PDMTHREADINT, but is placed here because of the
     * function pointer typedefs. So, don't touch these, please.
     */
    union
    {
        /** PDMTHREADTYPE_DEVICE data. */
        struct
        {
            /** The device instance. */
            PPDMDEVINSR3                        pDevIns;
            /** The thread function. */
            R3PTRTYPE(PFNPDMTHREADDEV)          pfnThread;
            /** Thread. */
            R3PTRTYPE(PFNPDMTHREADWAKEUPDEV)    pfnWakeUp;
        } Dev;

        /** PDMTHREADTYPE_USB data. */
        struct
        {
            /** The device instance. */
            PPDMUSBINS                          pUsbIns;
            /** The thread function. */
            R3PTRTYPE(PFNPDMTHREADUSB)          pfnThread;
            /** Thread. */
            R3PTRTYPE(PFNPDMTHREADWAKEUPUSB)    pfnWakeUp;
        } Usb;

        /** PDMTHREADTYPE_DRIVER data. */
        struct
        {
            /** The driver instance. */
            R3PTRTYPE(PPDMDRVINS)               pDrvIns;
            /** The thread function. */
            R3PTRTYPE(PFNPDMTHREADDRV)          pfnThread;
            /** Thread. */
            R3PTRTYPE(PFNPDMTHREADWAKEUPDRV)    pfnWakeUp;
        } Drv;

        /** PDMTHREADTYPE_INTERNAL data. */
        struct
        {
            /** The thread function. */
            R3PTRTYPE(PFNPDMTHREADINT)          pfnThread;
            /** Thread. */
            R3PTRTYPE(PFNPDMTHREADWAKEUPINT)    pfnWakeUp;
        } Int;

        /** PDMTHREADTYPE_EXTERNAL data. */
        struct
        {
            /** The thread function. */
            R3PTRTYPE(PFNPDMTHREADEXT)          pfnThread;
            /** Thread. */
            R3PTRTYPE(PFNPDMTHREADWAKEUPEXT)    pfnWakeUp;
        } Ext;
    } u;

    /** Internal data. */
    union
    {
#ifdef PDMTHREADINT_DECLARED
        PDMTHREADINT            s;
#endif
        uint8_t                 padding[64];
    } Internal;
} PDMTHREAD;

/** PDMTHREAD::u32Version value. */
#define PDMTHREAD_VERSION   0xef010000

#ifdef IN_RING3
VMMR3DECL(int) PDMR3ThreadCreate(PVM pVM, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADINT pfnThread,
                                 PFNPDMTHREADWAKEUPINT pfnWakeUp, size_t cbStack, RTTHREADTYPE enmType, const char *pszName);
VMMR3DECL(int) PDMR3ThreadCreateExternal(PVM pVM, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADEXT pfnThread,
                                         PFNPDMTHREADWAKEUPEXT pfnWakeUp, size_t cbStack, RTTHREADTYPE enmType, const char *pszName);
VMMR3DECL(int) PDMR3ThreadDestroy(PPDMTHREAD pThread, int *pRcThread);
VMMR3DECL(int) PDMR3ThreadIAmSuspending(PPDMTHREAD pThread);
VMMR3DECL(int) PDMR3ThreadIAmRunning(PPDMTHREAD pThread);
VMMR3DECL(int) PDMR3ThreadSleep(PPDMTHREAD pThread, RTMSINTERVAL cMillies);
VMMR3DECL(int) PDMR3ThreadSuspend(PPDMTHREAD pThread);
VMMR3DECL(int) PDMR3ThreadResume(PPDMTHREAD pThread);
#endif /* IN_RING3 */

/** @} */

RT_C_DECLS_END

#endif