[93969] | 1 | /** @file
|
---|
[98576] | 2 | * TstHGCMMock.h - Mocking framework for testing HGCM-based host services.
|
---|
[93969] | 3 | *
|
---|
[98576] | 4 | * The goal is to run host service + Vbgl code as unmodified as possible as
|
---|
| 5 | * part of testcases to gain test coverage which otherwise wouldn't possible
|
---|
| 6 | * for heavily user-centric features like Shared Clipboard or drag'n drop (DnD).
|
---|
| 7 | *
|
---|
| 8 | * Currently, though, it's only the service that runs unmodified, the
|
---|
| 9 | * testcases does custom Vbgl work.
|
---|
[93969] | 10 | */
|
---|
| 11 |
|
---|
| 12 | /*
|
---|
[98103] | 13 | * Copyright (C) 2022-2023 Oracle and/or its affiliates.
|
---|
[93969] | 14 | *
|
---|
[96407] | 15 | * This file is part of VirtualBox base platform packages, as
|
---|
| 16 | * available from https://www.virtualbox.org.
|
---|
[93972] | 17 | *
|
---|
[96407] | 18 | * This program is free software; you can redistribute it and/or
|
---|
| 19 | * modify it under the terms of the GNU General Public License
|
---|
| 20 | * as published by the Free Software Foundation, in version 3 of the
|
---|
| 21 | * License.
|
---|
| 22 | *
|
---|
| 23 | * This program is distributed in the hope that it will be useful, but
|
---|
| 24 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
| 25 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
| 26 | * General Public License for more details.
|
---|
| 27 | *
|
---|
| 28 | * You should have received a copy of the GNU General Public License
|
---|
| 29 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
| 30 | *
|
---|
[93972] | 31 | * The contents of this file may alternatively be used under the terms
|
---|
| 32 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 33 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
---|
| 34 | * in the VirtualBox distribution, in which case the provisions of the
|
---|
[93972] | 35 | * CDDL are applicable instead of those of the GPL.
|
---|
| 36 | *
|
---|
| 37 | * You may elect to license modified versions of this file under the
|
---|
| 38 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[96407] | 39 | *
|
---|
| 40 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[93969] | 41 | */
|
---|
[93972] | 42 |
|
---|
[98578] | 43 | #ifndef VBOX_INCLUDED_HostServices_TstHGCMMock_h
|
---|
| 44 | #define VBOX_INCLUDED_HostServices_TstHGCMMock_h
|
---|
[93970] | 45 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 46 | # pragma once
|
---|
| 47 | #endif
|
---|
[93969] | 48 |
|
---|
[98576] | 49 | #ifdef IN_RING3
|
---|
[93970] | 50 |
|
---|
| 51 | #include <iprt/list.h>
|
---|
[93969] | 52 | #include <VBox/VBoxGuestLib.h>
|
---|
[93970] | 53 | #include <VBox/hgcmsvc.h>
|
---|
[93969] | 54 |
|
---|
| 55 |
|
---|
| 56 | /** Simple call handle structure for the guest call completion callback. */
|
---|
[93970] | 57 | typedef struct VBOXHGCMCALLHANDLE_TYPEDEF
|
---|
[93969] | 58 | {
|
---|
| 59 | /** Where to store the result code on call completion. */
|
---|
| 60 | int32_t rc;
|
---|
[93970] | 61 | } VBOXHGCMCALLHANDLE_TYPEDEF;
|
---|
[93969] | 62 |
|
---|
| 63 | /**
|
---|
| 64 | * Enumeration for a HGCM mock function type.
|
---|
| 65 | */
|
---|
| 66 | typedef enum TSTHGCMMOCKFNTYPE
|
---|
| 67 | {
|
---|
| 68 | TSTHGCMMOCKFNTYPE_NONE = 0,
|
---|
| 69 | TSTHGCMMOCKFNTYPE_CONNECT,
|
---|
| 70 | TSTHGCMMOCKFNTYPE_DISCONNECT,
|
---|
| 71 | TSTHGCMMOCKFNTYPE_CALL,
|
---|
| 72 | TSTHGCMMOCKFNTYPE_HOST_CALL
|
---|
| 73 | } TSTHGCMMOCKFNTYPE;
|
---|
| 74 |
|
---|
[93970] | 75 | /** Pointer to a mock HGCM service. */
|
---|
| 76 | typedef struct TSTHGCMMOCKSVC *PTSTHGCMMOCKSVC;
|
---|
[93969] | 77 |
|
---|
| 78 | /**
|
---|
| 79 | * Structure for mocking a server-side HGCM client.
|
---|
| 80 | */
|
---|
| 81 | typedef struct TSTHGCMMOCKCLIENT
|
---|
| 82 | {
|
---|
| 83 | /** Pointer to to mock service instance this client belongs to. */
|
---|
[93970] | 84 | PTSTHGCMMOCKSVC pSvc;
|
---|
[93969] | 85 | /** Assigned HGCM client ID. */
|
---|
| 86 | uint32_t idClient;
|
---|
| 87 | /** Opaque pointer to service-specific client data.
|
---|
| 88 | * Can be NULL if not being used. */
|
---|
| 89 | void *pvClient;
|
---|
| 90 | /** Size (in bytes) of \a pvClient. */
|
---|
| 91 | size_t cbClient;
|
---|
| 92 | /** The client's current HGCM call handle. */
|
---|
| 93 | VBOXHGCMCALLHANDLE_TYPEDEF hCall;
|
---|
| 94 | /** Whether the current client call has an asynchronous
|
---|
| 95 | * call pending or not. */
|
---|
| 96 | bool fAsyncExec;
|
---|
| 97 | /** Event semaphore to signal call completion. */
|
---|
| 98 | RTSEMEVENT hEvent;
|
---|
| 99 | } TSTHGCMMOCKCLIENT;
|
---|
| 100 | /** Pointer to a mock HGCM client. */
|
---|
| 101 | typedef TSTHGCMMOCKCLIENT *PTSTHGCMMOCKCLIENT;
|
---|
| 102 |
|
---|
| 103 | /**
|
---|
| 104 | * Structure for keeping HGCM mock function parameters.
|
---|
| 105 | */
|
---|
| 106 | typedef struct TSTHGCMMOCKFN
|
---|
| 107 | {
|
---|
| 108 | /** List node for storing this struct into a queue. */
|
---|
| 109 | RTLISTNODE Node;
|
---|
| 110 | /** Function type. */
|
---|
| 111 | TSTHGCMMOCKFNTYPE enmType;
|
---|
| 112 | /** Pointer to associated client. */
|
---|
| 113 | PTSTHGCMMOCKCLIENT pClient;
|
---|
| 114 | /** Union keeping function-specific parameters,
|
---|
| 115 | * depending on \a enmType. */
|
---|
| 116 | union
|
---|
| 117 | {
|
---|
| 118 | struct
|
---|
| 119 | {
|
---|
| 120 | int32_t iFunc;
|
---|
| 121 | uint32_t cParms;
|
---|
| 122 | PVBOXHGCMSVCPARM pParms;
|
---|
| 123 | VBOXHGCMCALLHANDLE hCall;
|
---|
| 124 | } Call;
|
---|
| 125 | struct
|
---|
| 126 | {
|
---|
| 127 | int32_t iFunc;
|
---|
| 128 | uint32_t cParms;
|
---|
| 129 | PVBOXHGCMSVCPARM pParms;
|
---|
| 130 | } HostCall;
|
---|
| 131 | } u;
|
---|
| 132 | } TSTHGCMMOCKFN;
|
---|
| 133 | /** Pointer to a HGCM mock function parameters structure. */
|
---|
| 134 | typedef TSTHGCMMOCKFN *PTSTHGCMMOCKFN;
|
---|
| 135 |
|
---|
| 136 | /**
|
---|
| 137 | * Structure for keeping a HGCM mock service instance.
|
---|
| 138 | */
|
---|
| 139 | typedef struct TSTHGCMMOCKSVC
|
---|
| 140 | {
|
---|
| 141 | /** HGCM helper table to use. */
|
---|
| 142 | VBOXHGCMSVCHELPERS fnHelpers;
|
---|
| 143 | /** HGCM service function table to use. */
|
---|
| 144 | VBOXHGCMSVCFNTABLE fnTable;
|
---|
| 145 | /** Next HGCM client ID to assign.
|
---|
| 146 | * 0 is considered as being invalid. */
|
---|
| 147 | HGCMCLIENTID uNextClientId;
|
---|
| 148 | /** Array of connected HGCM mock clients.
|
---|
| 149 | * Currently limited to 4 clients maximum. */
|
---|
| 150 | TSTHGCMMOCKCLIENT aHgcmClient[4];
|
---|
| 151 | /** Thread handle for the service's main loop. */
|
---|
| 152 | RTTHREAD hThread;
|
---|
| 153 | /** Event semaphore for signalling a message
|
---|
| 154 | * queue change. */
|
---|
| 155 | RTSEMEVENT hEventQueue;
|
---|
[97268] | 156 | /** Event semaphore for clients connecting to the server. */
|
---|
| 157 | RTSEMEVENT hEventConnect;
|
---|
[93969] | 158 | /** Number of current host calls being served.
|
---|
| 159 | * Currently limited to one call at a time. */
|
---|
| 160 | uint8_t cHostCallers;
|
---|
| 161 | /** Result code of last returned host call. */
|
---|
| 162 | int rcHostCall;
|
---|
| 163 | /** Event semaphore for host calls. */
|
---|
| 164 | RTSEMEVENT hEventHostCall;
|
---|
| 165 | /** List (queue) of function calls to process. */
|
---|
| 166 | RTLISTANCHOR lstCall;
|
---|
| 167 | /** Shutdown indicator flag. */
|
---|
| 168 | volatile bool fShutdown;
|
---|
| 169 | } TSTHGCMMOCKSVC;
|
---|
| 170 |
|
---|
| 171 |
|
---|
[93970] | 172 | PTSTHGCMMOCKSVC TstHgcmMockSvcInst(void);
|
---|
| 173 | PTSTHGCMMOCKCLIENT TstHgcmMockSvcWaitForConnectEx(PTSTHGCMMOCKSVC pSvc, RTMSINTERVAL msTimeout);
|
---|
| 174 | PTSTHGCMMOCKCLIENT TstHgcmMockSvcWaitForConnect(PTSTHGCMMOCKSVC pSvc);
|
---|
[98574] | 175 | int TstHgcmMockSvcCreate(PTSTHGCMMOCKSVC pSvc);
|
---|
[93970] | 176 | int TstHgcmMockSvcDestroy(PTSTHGCMMOCKSVC pSvc);
|
---|
| 177 | int TstHgcmMockSvcStart(PTSTHGCMMOCKSVC pSvc);
|
---|
| 178 | int TstHgcmMockSvcStop(PTSTHGCMMOCKSVC pSvc);
|
---|
[93969] | 179 |
|
---|
[93970] | 180 | int TstHgcmMockSvcHostCall(PTSTHGCMMOCKSVC pSvc, void *pvService, int32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]);
|
---|
[93969] | 181 |
|
---|
[98576] | 182 | RT_C_DECLS_BEGIN
|
---|
| 183 | DECLCALLBACK(DECLEXPORT(int)) VBoxHGCMSvcLoad(VBOXHGCMSVCFNTABLE *pTable);
|
---|
| 184 | RT_C_DECLS_END
|
---|
| 185 |
|
---|
| 186 | # undef VBGLR3DECL
|
---|
| 187 | # define VBGLR3DECL(type) DECL_HIDDEN_NOTHROW(type) VBOXCALL
|
---|
[93970] | 188 | VBGLR3DECL(int) VbglR3HGCMConnect(const char *pszServiceName, HGCMCLIENTID *pidClient);
|
---|
| 189 | VBGLR3DECL(int) VbglR3HGCMDisconnect(HGCMCLIENTID idClient);
|
---|
[98531] | 190 | VBGLR3DECL(int) VbglR3GetSessionId(uint64_t *pu64IdSession);
|
---|
[93970] | 191 | VBGLR3DECL(int) VbglR3HGCMCall(PVBGLIOCHGCMCALL pInfo, size_t cbInfo);
|
---|
| 192 |
|
---|
| 193 |
|
---|
| 194 | #endif /* IN_RING3 */
|
---|
| 195 |
|
---|
[98578] | 196 | #endif /* !VBOX_INCLUDED_HostServices_TstHGCMMock_h */
|
---|