VirtualBox

source: vbox/trunk/include/VBox/HostServices/TstHGCMMockUtils.h@ 103224

Last change on this file since 103224 was 98578, checked in by vboxsync, 22 months ago

HGCMMock*.h: Moved to HostServices as it chiefly tests the HGCM services, not so much shared guest/host code is the previous location would indicate.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.8 KB
Line 
1/** @file
2 * TstHGCMMockUtils.h - Utility functions for the HGCM Mocking framework.
3 *
4 * The utility functions are optional to the actual HGCM Mocking framework and
5 * can support testcases which require a more advanced setup.
6 *
7 * With this one can setup host and guest side threads, which in turn can simulate
8 * specific host (i.e. HGCM service) + guest (i.e. like in the Guest Addditions
9 * via VbglR3) scenarios.
10 *
11 * Glossary:
12 *
13 * Host thread:
14 * - The host thread is used as part of the actual HGCM service being tested and
15 * provides callbacks (@see TSTHGCMUTILSHOSTCALLBACKS) for the unit test.
16 * Guest thread:
17 * - The guest thread is used as part of the guest side and mimics
18 * VBoxClient / VBoxTray / VBoxService parts. (i.e. for VbglR3 calls).
19 * Task:
20 * - A task is the simplest unit of test execution and used between the guest
21 * and host mocking threads.
22 *
23 ** @todo Add TstHGCMSimpleHost / TstHGCMSimpleGuest wrappers along those lines:
24 * Callback.pfnOnClientConnected = tstOnHostClientConnected()
25 * TstHGCMSimpleHostInitAndStart(&Callback)
26 * Callback.pfnOnConnected = tstOnGuestConnected()
27 * TstHGCMSimpleClientInitAndStart(&Callback)
28 */
29
30/*
31 * Copyright (C) 2022-2023 Oracle and/or its affiliates.
32 *
33 * This file is part of VirtualBox base platform packages, as
34 * available from https://www.virtualbox.org.
35 *
36 * This program is free software; you can redistribute it and/or
37 * modify it under the terms of the GNU General Public License
38 * as published by the Free Software Foundation, in version 3 of the
39 * License.
40 *
41 * This program is distributed in the hope that it will be useful, but
42 * WITHOUT ANY WARRANTY; without even the implied warranty of
43 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
44 * General Public License for more details.
45 *
46 * You should have received a copy of the GNU General Public License
47 * along with this program; if not, see <https://www.gnu.org/licenses>.
48 *
49 * The contents of this file may alternatively be used under the terms
50 * of the Common Development and Distribution License Version 1.0
51 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
52 * in the VirtualBox distribution, in which case the provisions of the
53 * CDDL are applicable instead of those of the GPL.
54 *
55 * You may elect to license modified versions of this file under the
56 * terms and conditions of either the GPL or the CDDL or both.
57 *
58 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
59 */
60
61#ifndef VBOX_INCLUDED_HostServices_TstHGCMMockUtils_h
62#define VBOX_INCLUDED_HostServices_TstHGCMMockUtils_h
63#ifndef RT_WITHOUT_PRAGMA_ONCE
64# pragma once
65#endif
66
67#include <VBox/HostServices/TstHGCMMock.h>
68
69/** Pointer to a HGCM Mock utils context. */
70typedef struct TSTHGCMUTILSCTX *PTSTHGCMUTILSCTX;
71
72/**
73 * Structure for keeping a HGCM Mock utils host service callback table.
74 */
75typedef struct TSTHGCMUTILSHOSTCALLBACKS
76{
77 DECLCALLBACKMEMBER(int, pfnOnClientConnected,(PTSTHGCMUTILSCTX pCtx, PTSTHGCMMOCKCLIENT pClient, void *pvUser));
78} TSTHGCMUTILSHOSTCALLBACKS;
79/** Pointer to a HGCM Mock utils host callbacks table. */
80typedef TSTHGCMUTILSHOSTCALLBACKS *PTSTHGCMUTILSHOSTCALLBACKS;
81
82/**
83 * Structure for keeping a generic HGCM Mock utils task.
84 *
85 * A task is a single test unit / entity.
86 */
87typedef struct TSTHGCMUTILSTASK
88{
89 /** Completion event. */
90 RTSEMEVENT hEvent;
91 /** Completion rc.
92 * Set to VERR_IPE_UNINITIALIZED_STATUS if not completed yet. */
93 int rcCompleted;
94 /** Expected completion rc. */
95 int rcExpected;
96 /** Pointer to opaque (testcase-specific) task parameters.
97 * Might be NULL if not needed / used. */
98 void *pvUser;
99} TSTHGCMUTILSTASK;
100/** Pointer to a HGCM Mock utils task. */
101typedef TSTHGCMUTILSTASK *PTSTHGCMUTILSTASK;
102
103/** Callback function for HGCM Mock utils threads. */
104typedef DECLCALLBACKTYPE(int, FNTSTHGCMUTILSTHREAD,(PTSTHGCMUTILSCTX pCtx, void *pvUser));
105/** Pointer to a HGCM Mock utils guest thread callback. */
106typedef FNTSTHGCMUTILSTHREAD *PFNTSTHGCMUTILSTHREAD;
107
108/**
109 * Structure for keeping a HGCM Mock utils context.
110 */
111typedef struct TSTHGCMUTILSCTX
112{
113 /** Pointer to the HGCM Mock service instance to use. */
114 PTSTHGCMMOCKSVC pSvc;
115 /** Currently we only support one task at a time. */
116 TSTHGCMUTILSTASK Task;
117 struct
118 {
119 RTTHREAD hThread;
120 volatile bool fShutdown;
121 PFNTSTHGCMUTILSTHREAD pfnThread;
122 void *pvUser;
123 } Guest;
124 struct
125 {
126 RTTHREAD hThread;
127 volatile bool fShutdown;
128 TSTHGCMUTILSHOSTCALLBACKS Callbacks;
129 void *pvUser;
130 } Host;
131} TSTHGCMUTILSCTX;
132
133
134/** @name Context handling.
135 * @{ */
136void TstHGCMUtilsCtxInit(PTSTHGCMUTILSCTX pCtx, PTSTHGCMMOCKSVC pSvc);
137/** @} */
138
139/** @name Task handling.
140 * @{ */
141PTSTHGCMUTILSTASK TstHGCMUtilsTaskGetCurrent(PTSTHGCMUTILSCTX pCtx);
142int TstHGCMUtilsTaskInit(PTSTHGCMUTILSTASK pTask);
143void TstHGCMUtilsTaskDestroy(PTSTHGCMUTILSTASK pTask);
144int TstHGCMUtilsTaskWait(PTSTHGCMUTILSTASK pTask, RTMSINTERVAL msTimeout);
145bool TstHGCMUtilsTaskOk(PTSTHGCMUTILSTASK pTask);
146bool TstHGCMUtilsTaskCompleted(PTSTHGCMUTILSTASK pTask);
147void TstHGCMUtilsTaskSignal(PTSTHGCMUTILSTASK pTask, int rc);
148/** @} */
149
150/** @name Threading.
151 * @{ */
152int TstHGCMUtilsGuestThreadStart(PTSTHGCMUTILSCTX pCtx, PFNTSTHGCMUTILSTHREAD pFnThread, void *pvUser);
153int TstHGCMUtilsGuestThreadStop(PTSTHGCMUTILSCTX pCtx);
154int TstHGCMUtilsHostThreadStart(PTSTHGCMUTILSCTX pCtx, PTSTHGCMUTILSHOSTCALLBACKS pCallbacks, void *pvUser);
155int TstHGCMUtilsHostThreadStop(PTSTHGCMUTILSCTX pCtx);
156/** @} */
157
158
159#endif /* !VBOX_INCLUDED_HostServices_TstHGCMMockUtils_h */
160
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette