From f215e02bf85f68d3a6106c2a1f4f7f063f819064 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 11 Apr 2024 10:17:27 +0200 Subject: Adding upstream version 7.0.14-dfsg. Signed-off-by: Daniel Baumann --- src/VBox/Main/include/HGCMThread.h | 238 +++++++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 src/VBox/Main/include/HGCMThread.h (limited to 'src/VBox/Main/include/HGCMThread.h') diff --git a/src/VBox/Main/include/HGCMThread.h b/src/VBox/Main/include/HGCMThread.h new file mode 100644 index 00000000..cbb96538 --- /dev/null +++ b/src/VBox/Main/include/HGCMThread.h @@ -0,0 +1,238 @@ +/* $Id: HGCMThread.h $ */ +/** @file + * HGCMThread - Host-Guest Communication Manager worker threads header. + */ + +/* + * Copyright (C) 2006-2023 Oracle and/or its affiliates. + * + * This file is part of VirtualBox base platform packages, as + * available from https://www.virtualbox.org. + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation, in version 3 of the + * License. + * + * This program 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 + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, see . + * + * SPDX-License-Identifier: GPL-3.0-only + */ + +#ifndef MAIN_INCLUDED_HGCMThread_h +#define MAIN_INCLUDED_HGCMThread_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include + +#include "HGCMObjects.h" + +/* Forward declaration of the worker thread class. */ +class HGCMThread; + +/** A handle for HGCM message. */ +typedef uint32_t HGCMMSGHANDLE; + +/* Forward declaration of message core class. */ +class HGCMMsgCore; + +/** @todo comment */ + +typedef HGCMMsgCore *FNHGCMNEWMSGALLOC(uint32_t u32MsgId); +typedef FNHGCMNEWMSGALLOC *PFNHGCMNEWMSGALLOC; + +/** Function that is called after message processing by worker thread, + * or if an error occurred during message handling after successfully + * posting (hgcmMsgPost) the message to worker thread. + * + * @param result Return code either from the service which actually processed the message + * or from HGCM. + * @param pMsgCore Pointer to just processed message. + * + * @return Restricted set of VBox status codes when guest call message: + * @retval VINF_SUCCESS on success + * @retval VERR_CANCELLED if the request was cancelled. + * @retval VERR_ALREADY_RESET if the VM is resetting. + * @retval VERR_NOT_AVAILABLE if HGCM has been disconnected from the VMMDev + * (shouldn't happen). + */ +typedef DECLCALLBACKTYPE(int, FNHGCMMSGCALLBACK,(int32_t result, HGCMMsgCore *pMsgCore)); +/** Pointer to a message completeion callback function. */ +typedef FNHGCMMSGCALLBACK *PFNHGCMMSGCALLBACK; + + +/** HGCM core message. */ +class HGCMMsgCore : public HGCMReferencedObject +{ + private: + friend class HGCMThread; + + /** Version of message header. */ + uint32_t m_u32Version; + + /** Message number/identifier. */ + uint32_t m_u32Msg; + + /** Thread the message belongs to, referenced by the message. */ + HGCMThread *m_pThread; + + /** Callback function pointer. */ + PFNHGCMMSGCALLBACK m_pfnCallback; + + /** Next element in a message queue. */ + HGCMMsgCore *m_pNext; + /** Previous element in a message queue. + * @todo seems not necessary. */ + HGCMMsgCore *m_pPrev; + + /** Various internal flags. */ + uint32_t m_fu32Flags; + + /** Result code for a Send */ + int32_t m_vrcSend; + + protected: + void InitializeCore(uint32_t u32MsgId, HGCMThread *pThread); + + virtual ~HGCMMsgCore(); + + public: + HGCMMsgCore() : HGCMReferencedObject(HGCMOBJ_MSG) {}; + + uint32_t MsgId(void) { return m_u32Msg; }; + + HGCMThread *Thread(void) { return m_pThread; }; + + /** Initialize message after it was allocated. */ + virtual void Initialize(void) {}; + + /** Uninitialize message. */ + virtual void Uninitialize(void) {}; +}; + + +/** HGCM worker thread function. + * + * @param pThread The HGCM thread instance. + * @param pvUser User specified thread parameter. + */ +typedef DECLCALLBACKTYPE(void, FNHGCMTHREAD,(HGCMThread *pThread, void *pvUser)); +typedef FNHGCMTHREAD *PFNHGCMTHREAD; + + +/** + * Thread API. + * Based on thread handles. Internals of a thread are not exposed to users. + */ + +/** Initialize threads. + * + * @return VBox status code. + */ +int hgcmThreadInit(void); +void hgcmThreadUninit(void); + + +/** Create a HGCM worker thread. + * + * @param ppThread Where to return the pointer to the worker thread. + * @param pszThreadName Name of the thread, needed by runtime. + * @param pfnThread The worker thread function. + * @param pvUser A pointer passed to worker thread. + * @param pszStatsSubDir The "sub-directory" under "/HGCM/" where thread + * statistics should be registered. The caller, + * HGCMService, will deregister them. NULL if no stats. + * @param pUVM The user mode VM handle to register statistics with. + * NULL if no stats. + * @param pVMM The VMM vtable for statistics registration. NULL if + * no stats. + * + * @return VBox status code. + */ +int hgcmThreadCreate(HGCMThread **ppThread, const char *pszThreadName, PFNHGCMTHREAD pfnThread, void *pvUser, + const char *pszStatsSubDir, PUVM pUVM, PCVMMR3VTABLE pVMM); + +/** Wait for termination of a HGCM worker thread. + * + * @param pThread The HGCM thread. The passed in reference is always + * consumed. + * + * @return VBox status code. + */ +int hgcmThreadWait(HGCMThread *pThread); + +/** Allocate a message to be posted to HGCM worker thread. + * + * @param pThread The HGCM worker thread. + * @param ppHandle Where to store the pointer to the new message. + * @param u32MsgId Message identifier. + * @param pfnNewMessage New message allocation callback. + * + * @return VBox status code. + */ +int hgcmMsgAlloc(HGCMThread *pThread, HGCMMsgCore **ppHandle, uint32_t u32MsgId, PFNHGCMNEWMSGALLOC pfnNewMessage); + +/** Post a message to HGCM worker thread. + * + * @param pMsg The message. Reference will be consumed! + * @param pfnCallback Message completion callback. + * + * @return VBox status code. + * @retval VINF_HGCM_ASYNC_EXECUTE on success. + * + * @thread any + */ +int hgcmMsgPost(HGCMMsgCore *pMsg, PFNHGCMMSGCALLBACK pfnCallback); + +/** Send a message to HGCM worker thread. + * + * The function will return after message is processed by thread. + * + * @param pMsg The message. Reference will be consumed! + * + * @return VBox status code. + * + * @thread any + */ +int hgcmMsgSend(HGCMMsgCore *pMsg); + + +/* Wait for and get a message. + * + * @param pThread The HGCM worker thread. + * @param ppMsg Where to store returned message pointer. + * + * @return VBox status code. + * + * @thread worker thread + */ +int hgcmMsgGet(HGCMThread *pThread, HGCMMsgCore **ppMsg); + + +/** Worker thread has processed a message previously obtained with hgcmMsgGet. + * + * @param pMsg Processed message pointer. + * @param result Result code, VBox status code. + * + * @return Restricted set of VBox status codes when guest call message: + * @retval VINF_SUCCESS on success + * @retval VERR_CANCELLED if the request was cancelled. + * @retval VERR_ALREADY_RESET if the VM is resetting. + * @retval VERR_NOT_AVAILABLE if HGCM has been disconnected from the VMMDev + * (shouldn't happen). + * + * @thread worker thread + */ +int hgcmMsgComplete(HGCMMsgCore *pMsg, int32_t result); + + +#endif /* !MAIN_INCLUDED_HGCMThread_h */ + -- cgit v1.2.3