Context Navigation

← Previous Revision
Next Revision →
Blame
Revision Log

vboxwrappers.py

Last change on this file was 103702, checked in by vboxsync, 3 months ago
ValidationKit: bugref:10318 Enable smoke test for Hyper-V enabled Windows 10 Pro guest.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 151.4 KB

Line
1	# -- coding: utf-8 --
2	# $Id: vboxwrappers.py 103702 2024-03-06 13:37:56Z vboxsync $
3	# pylint: disable=too-many-lines
4
5	"""
6	VirtualBox Wrapper Classes
7	"""
8
9	__copyright__ = \
10	"""
11	Copyright (C) 2010-2023 Oracle and/or its affiliates.
12
13	This file is part of VirtualBox base platform packages, as
14	available from https://www.virtualbox.org.
15
16	This program is free software; you can redistribute it and/or
17	modify it under the terms of the GNU General Public License
18	as published by the Free Software Foundation, in version 3 of the
19	License.
20
21	This program is distributed in the hope that it will be useful, but
22	WITHOUT ANY WARRANTY; without even the implied warranty of
23	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24	General Public License for more details.
25
26	You should have received a copy of the GNU General Public License
27	along with this program; if not, see <https://www.gnu.org/licenses>.
28
29	The contents of this file may alternatively be used under the terms
30	of the Common Development and Distribution License Version 1.0
31	(CDDL), a copy of it is provided in the "COPYING.CDDL" file included
32	in the VirtualBox distribution, in which case the provisions of the
33	CDDL are applicable instead of those of the GPL.
34
35	You may elect to license modified versions of this file under the
36	terms and conditions of either the GPL or the CDDL or both.
37
38	SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
39	"""
40	__version__ = "$Revision: 103702 $"
41
42
43	# Standard Python imports.
44	import os;
45	import socket;
46	import sys;
47	import uuid;
48
49	# Validation Kit imports.
50	from common import utils;
51	from common import netutils;
52	from testdriver import base;
53	from testdriver import reporter;
54	from testdriver import txsclient;
55	from testdriver import vboxcon;
56	from testdriver import vbox;
57	from testdriver.base import TdTaskBase;
58
59
60	def _ControllerNameToBusAndType(sController):
61	""" Translate a controller name to a storage bus. """
62	if sController == "IDE Controller":
63	eBus = vboxcon.StorageBus_IDE;
64	eType = vboxcon.StorageControllerType_PIIX4;
65	elif sController == "SATA Controller":
66	eBus = vboxcon.StorageBus_SATA;
67	eType = vboxcon.StorageControllerType_IntelAhci;
68	elif sController == "Floppy Controller":
69	eType = vboxcon.StorageControllerType_I82078;
70	eBus = vboxcon.StorageBus_Floppy;
71	elif sController == "SAS Controller":
72	eBus = vboxcon.StorageBus_SAS;
73	eType = vboxcon.StorageControllerType_LsiLogicSas;
74	elif sController == "SCSI Controller":
75	eBus = vboxcon.StorageBus_SCSI;
76	eType = vboxcon.StorageControllerType_LsiLogic;
77	elif sController == "BusLogic SCSI Controller":
78	eBus = vboxcon.StorageBus_SCSI;
79	eType = vboxcon.StorageControllerType_BusLogic;
80	elif sController == "NVMe Controller":
81	eBus = vboxcon.StorageBus_PCIe;
82	eType = vboxcon.StorageControllerType_NVMe;
83	elif sController == "VirtIO SCSI Controller":
84	eBus = vboxcon.StorageBus_VirtioSCSI;
85	eType = vboxcon.StorageControllerType_VirtioSCSI;
86	else:
87	eBus = vboxcon.StorageBus_Null;
88	eType = vboxcon.StorageControllerType_Null;
89	return (eBus, eType);
90
91
92	def _nameMachineState(eState):
93	""" Gets the name (string) of a machine state."""
94	if eState == vboxcon.MachineState_PoweredOff: return 'PoweredOff';
95	if eState == vboxcon.MachineState_Saved: return 'Saved';
96	if eState == vboxcon.MachineState_Teleported: return 'Teleported';
97	if eState == vboxcon.MachineState_Aborted: return 'Aborted';
98	if eState == vboxcon.MachineState_Running: return 'Running';
99	if eState == vboxcon.MachineState_Paused: return 'Paused';
100	if eState == vboxcon.MachineState_Stuck: return 'GuruMeditation';
101	if eState == vboxcon.MachineState_Teleporting: return 'Teleporting';
102	if eState == vboxcon.MachineState_LiveSnapshotting: return 'LiveSnapshotting';
103	if eState == vboxcon.MachineState_Starting: return 'Starting';
104	if eState == vboxcon.MachineState_Stopping: return 'Stopping';
105	if eState == vboxcon.MachineState_Saving: return 'Saving';
106	if eState == vboxcon.MachineState_Restoring: return 'Restoring';
107	if eState == vboxcon.MachineState_TeleportingPausedVM: return 'TeleportingPausedVM';
108	if eState == vboxcon.MachineState_TeleportingIn: return 'TeleportingIn';
109	if eState == vboxcon.MachineState_DeletingSnapshotOnline: return 'DeletingSnapshotOnline';
110	if eState == vboxcon.MachineState_DeletingSnapshotPaused: return 'DeletingSnapshotPaused';
111	if eState == vboxcon.MachineState_RestoringSnapshot: return 'RestoringSnapshot';
112	if eState == vboxcon.MachineState_DeletingSnapshot: return 'DeletingSnapshot';
113	if eState == vboxcon.MachineState_SettingUp: return 'SettingUp';
114	if hasattr(vboxcon, 'MachineState_FaultTolerantSyncing'):
115	if eState == vboxcon.MachineState_FaultTolerantSyncing: return 'FaultTolerantSyncing';
116	if hasattr(vboxcon, 'MachineState_AbortedSaved'): # since r147033 / 7.0
117	if eState == vboxcon.MachineState_AbortedSaved: return 'Aborted-Saved';
118	return 'Unknown-%s' % (eState,);
119
120
121	class VirtualBoxWrapper(object): # pylint: disable=too-few-public-methods
122	"""
123	Wrapper around the IVirtualBox object that adds some (hopefully) useful
124	utility methods
125
126	The real object can be accessed thru the o member. That said, members can
127	be accessed directly as well.
128	"""
129
130	def __init__(self, oVBox, oVBoxMgr, fpApiVer, oTstDrv):
131	self.o = oVBox;
132	self.oVBoxMgr = oVBoxMgr;
133	self.fpApiVer = fpApiVer;
134	self.oTstDrv = oTstDrv;
135
136	def __getattr__(self, sName):
137	# Try ourselves first.
138	try:
139	oAttr = self.__dict__[sName];
140	except:
141	#try:
142	# oAttr = dir(self)[sName];
143	#except AttributeError:
144	oAttr = getattr(self.o, sName);
145	return oAttr;
146
147	#
148	# Utilities.
149	#
150
151	def registerDerivedEventHandler(self, oSubClass, dArgs = None):
152	"""
153	Create an instance of the given VirtualBoxEventHandlerBase sub-class
154	and register it.
155
156	The new instance is returned on success. None is returned on error.
157	"""
158	dArgsCopy = dArgs.copy() if dArgs is not None else {};
159	dArgsCopy['oVBox'] = self;
160	return oSubClass.registerDerivedEventHandler(self.oVBoxMgr, self.fpApiVer, oSubClass, dArgsCopy,
161	self.o, 'IVirtualBox', 'IVirtualBoxCallback');
162
163	def deleteHdByLocation(self, sHdLocation):
164	"""
165	Deletes a disk image from the host, given it's location.
166	Returns True on success and False on failure. Error information is logged.
167	"""
168	try:
169	oIMedium = self.o.findHardDisk(sHdLocation);
170	except:
171	try:
172	if self.fpApiVer >= 4.1:
173	oIMedium = self.o.openMedium(sHdLocation, vboxcon.DeviceType_HardDisk,
174	vboxcon.AccessMode_ReadWrite, False);
175	elif self.fpApiVer >= 4.0:
176	oIMedium = self.o.openMedium(sHdLocation, vboxcon.DeviceType_HardDisk,
177	vboxcon.AccessMode_ReadWrite);
178	else:
179	oIMedium = self.o.openHardDisk(sHdLocation, vboxcon.AccessMode_ReadOnly, False, "", False, "");
180	except:
181	return reporter.errorXcpt('failed to open hd "%s"' % (sHdLocation));
182	return self.deleteHdByMedium(oIMedium)
183
184	def deleteHdByMedium(self, oIMedium):
185	"""
186	Deletes a disk image from the host, given an IMedium reference.
187	Returns True on success and False on failure. Error information is logged.
188	"""
189	try: oProgressCom = oIMedium.deleteStorage();
190	except: return reporter.errorXcpt('deleteStorage() for disk %s failed' % (oIMedium,));
191	try: oProgress = ProgressWrapper(oProgressCom, self.oVBoxMgr, self.oTstDrv, 'delete disk %s' % (oIMedium.location));
192	except: return reporter.errorXcpt();
193	oProgress.wait();
194	oProgress.logResult();
195	return oProgress.isSuccess();
196
197
198
199	class ProgressWrapper(TdTaskBase):
200	"""
201	Wrapper around a progress object for making it a task and providing useful
202	utility methods.
203	The real progress object can be accessed thru the o member.
204	"""
205
206	def __init__(self, oProgress, oVBoxMgr, oTstDrv, sName):
207	TdTaskBase.__init__(self, utils.getCallerName());
208	self.o = oProgress;
209	self.oVBoxMgr = oVBoxMgr;
210	self.oTstDrv = oTstDrv;
211	self.sName = sName;
212
213	def toString(self):
214	return '<%s sName=%s, oProgress=%s >' \
215	% (TdTaskBase.toString(self), self.sName, self.o);
216
217	#
218	# TdTaskBase overrides.
219	#
220
221	def pollTask(self, fLocked = False):
222	"""
223	Overrides TdTaskBase.pollTask().
224
225	This method returns False until the progress object has completed.
226	"""
227	self.doQuickApiTest();
228	try:
229	try:
230	if self.o.completed:
231	return True;
232	except:
233	pass;
234	finally:
235	self.oTstDrv.processPendingEvents();
236	return False;
237
238	def waitForTask(self, cMsTimeout = 0):
239	"""
240	Overrides TdTaskBase.waitForTask().
241	Process XPCOM/COM events while waiting.
242	"""
243	msStart = base.timestampMilli();
244	fState = self.pollTask(False);
245	while not fState:
246	cMsElapsed = base.timestampMilli() - msStart;
247	if cMsElapsed > cMsTimeout:
248	break;
249	cMsToWait = cMsTimeout - cMsElapsed;
250	cMsToWait = min(cMsToWait, 500);
251	try:
252	self.o.waitForCompletion(cMsToWait);
253	except KeyboardInterrupt: raise;
254	except: pass;
255	if self.fnProcessEvents:
256	self.fnProcessEvents();
257	reporter.doPollWork('ProgressWrapper.waitForTask');
258	fState = self.pollTask(False);
259	return fState;
260
261	#
262	# Utility methods.
263	#
264
265	def isSuccess(self):
266	"""
267	Tests if the progress object completed successfully.
268	Returns True on success, False on failure or incomplete.
269	"""
270	if not self.isCompleted():
271	return False;
272	return self.getResult() >= 0;
273
274	def isCompleted(self):
275	"""
276	Wrapper around IProgress.completed.
277	"""
278	return self.pollTask();
279
280	def isCancelable(self):
281	"""
282	Wrapper around IProgress.cancelable.
283	"""
284	try:
285	fRc = self.o.cancelable;
286	except:
287	reporter.logXcpt();
288	fRc = False;
289	return fRc;
290
291	def wasCanceled(self):
292	"""
293	Wrapper around IProgress.canceled.
294	"""
295	try:
296	fRc = self.o.canceled;
297	except:
298	reporter.logXcpt(self.sName);
299	fRc = False;
300	return fRc;
301
302	def cancel(self):
303	"""
304	Wrapper around IProgress.cancel()
305	Returns True on success, False on failure (logged as error).
306	"""
307	try:
308	self.o.cancel();
309	except:
310	reporter.errorXcpt(self.sName);
311	return False;
312	return True;
313
314	def getResult(self):
315	"""
316	Wrapper around IProgress.resultCode.
317	"""
318	try:
319	iRc = self.o.resultCode;
320	except:
321	reporter.logXcpt(self.sName);
322	iRc = -1;
323	return iRc;
324
325	def getErrInfoResultCode(self):
326	"""
327	Wrapper around IProgress.errorInfo.resultCode.
328
329	Returns the string on success, -1 on bad objects (logged as error), and
330	-2 on missing errorInfo object.
331	"""
332	iRc = -1;
333	try:
334	oErrInfo = self.o.errorInfo;
335	except:
336	reporter.errorXcpt(self.sName);
337	else:
338	if oErrInfo is None:
339	iRc = -2;
340	else:
341	try:
342	iRc = oErrInfo.resultCode;
343	except:
344	reporter.errorXcpt();
345	return iRc;
346
347	def getErrInfoText(self):
348	"""
349	Wrapper around IProgress.errorInfo.text.
350
351	Returns the string on success, None on failure. Missing errorInfo is
352	not logged as an error, all other failures are.
353	"""
354	sText = None;
355	try:
356	oErrInfo = self.o.errorInfo;
357	except:
358	reporter.log2Xcpt(self.sName);
359	else:
360	if oErrInfo is not None:
361	try:
362	sText = oErrInfo.text;
363	except:
364	reporter.errorXcpt();
365	return sText;
366
367	def stringifyErrorInfo(self):
368	"""
369	Formats IProgress.errorInfo into a string.
370	"""
371	try:
372	oErrInfo = self.o.errorInfo;
373	except:
374	reporter.logXcpt(self.sName);
375	sErr = 'no error info';
376	else:
377	sErr = vbox.stringifyErrorInfo(oErrInfo);
378	return sErr;
379
380	def stringifyResult(self):
381	"""
382	Stringify the result.
383	"""
384	if self.isCompleted():
385	if self.wasCanceled():
386	sRet = 'Progress %s: Canceled, hrc=%s' % (self.sName, vbox.ComError.toString(self.getResult()));
387	elif self.getResult() == 0:
388	sRet = 'Progress %s: Success' % (self.sName,);
389	elif self.getResult() > 0:
390	sRet = 'Progress %s: Success (hrc=%s)' % (self.sName, vbox.ComError.toString(self.getResult()));
391	else:
392	sRet = 'Progress %s: Failed! %s' % (self.sName, self.stringifyErrorInfo());
393	else:
394	sRet = 'Progress %s: Not completed yet...' % (self.sName);
395	return sRet;
396
397	def logResult(self, fIgnoreErrors = False):
398	"""
399	Logs the result, failure logged as error unless fIgnoreErrors is True.
400	Return True on success, False on failure (and fIgnoreErrors is false).
401	"""
402	sText = self.stringifyResult();
403	if self.isCompleted() and self.getResult() < 0 and fIgnoreErrors is False:
404	return reporter.error(sText);
405	reporter.log(sText);
406	return True;
407
408	def waitOnProgress(self, cMsInterval = 1000):
409	"""
410	See vbox.TestDriver.waitOnProgress.
411	"""
412	self.doQuickApiTest();
413	return self.oTstDrv.waitOnProgress(self.o, cMsInterval);
414
415	def wait(self, cMsTimeout = 60000, fErrorOnTimeout = True, cMsInterval = 1000):
416	"""
417	Wait on the progress object for a while.
418
419	Returns the resultCode of the progress object if completed.
420	Returns -1 on timeout, logged as error if fErrorOnTimeout is set.
421	Returns -2 is the progress object is invalid or waitForCompletion
422	fails (logged as errors).
423	"""
424	msStart = base.timestampMilli();
425	while True:
426	self.oTstDrv.processPendingEvents();
427	self.doQuickApiTest();
428	try:
429	if self.o.completed:
430	break;
431	except:
432	reporter.errorXcpt(self.sName);
433	return -2;
434	self.oTstDrv.processPendingEvents();
435
436	cMsElapsed = base.timestampMilli() - msStart;
437	if cMsElapsed > cMsTimeout:
438	if fErrorOnTimeout:
439	reporter.error('Timing out after waiting for %u s on "%s"' % (cMsTimeout / 1000, self.sName))
440	return -1;
441
442	try:
443	self.o.waitForCompletion(cMsInterval);
444	except:
445	reporter.errorXcpt(self.sName);
446	return -2;
447	reporter.doPollWork('ProgressWrapper.wait');
448
449	try:
450	rc = self.o.resultCode;
451	except:
452	rc = -2;
453	reporter.errorXcpt(self.sName);
454	self.oTstDrv.processPendingEvents();
455	return rc;
456
457	def waitForOperation(self, iOperation, cMsTimeout = 60000, fErrorOnTimeout = True, cMsInterval = 1000, \
458	fIgnoreErrors = False):
459	"""
460	Wait for the completion of a operation.
461
462	Negative iOperation values are relative to operationCount (this
463	property may changed at runtime).
464
465	Returns 0 if the operation completed normally.
466	Returns -1 on timeout, logged as error if fErrorOnTimeout is set.
467	Returns -2 is the progress object is invalid or waitForCompletion
468	fails (logged as errors).
469	Returns -3 if if the operation completed with an error, this is logged
470	as an error.
471	"""
472	msStart = base.timestampMilli();
473	while True:
474	self.oTstDrv.processPendingEvents();
475	self.doQuickApiTest();
476	try:
477	iCurrentOperation = self.o.operation;
478	cOperations = self.o.operationCount;
479	if iOperation >= 0:
480	iRealOperation = iOperation;
481	else:
482	iRealOperation = cOperations + iOperation;
483
484	if iCurrentOperation > iRealOperation:
485	return 0;
486	if iCurrentOperation == iRealOperation \
487	and iRealOperation >= cOperations - 1 \
488	and self.o.completed:
489	if self.o.resultCode < 0:
490	self.logResult(fIgnoreErrors);
491	return -3;
492	return 0;
493	except:
494	if fIgnoreErrors:
495	reporter.logXcpt();
496	else:
497	reporter.errorXcpt();
498	return -2;
499	self.oTstDrv.processPendingEvents();
500
501	cMsElapsed = base.timestampMilli() - msStart;
502	if cMsElapsed > cMsTimeout:
503	if fErrorOnTimeout:
504	if fIgnoreErrors:
505	reporter.log('Timing out after waiting for %s s on "%s" operation %d' \
506	% (cMsTimeout / 1000, self.sName, iOperation))
507	else:
508	reporter.error('Timing out after waiting for %s s on "%s" operation %d' \
509	% (cMsTimeout / 1000, self.sName, iOperation))
510	return -1;
511
512	try:
513	self.o.waitForOperationCompletion(iRealOperation, cMsInterval);
514	except:
515	if fIgnoreErrors:
516	reporter.logXcpt(self.sName);
517	else:
518	reporter.errorXcpt(self.sName);
519	return -2;
520	reporter.doPollWork('ProgressWrapper.waitForOperation');
521	# Not reached.
522	return -3; # Make pylin happy (for now).
523
524	def doQuickApiTest(self):
525	"""
526	Queries everything that is stable and easy to get at and checks that
527	they don't throw errors.
528	"""
529	if True is True: # pylint: disable=comparison-with-itself,comparison-of-constants
530	try:
531	iPct = self.o.operationPercent;
532	sDesc = self.o.description;
533	fCancelable = self.o.cancelable;
534	cSecsRemain = self.o.timeRemaining;
535	fCanceled = self.o.canceled;
536	fCompleted = self.o.completed;
537	iOp = self.o.operation;
538	cOps = self.o.operationCount;
539	iOpPct = self.o.operationPercent;
540	sOpDesc = self.o.operationDescription;
541	except:
542	reporter.errorXcpt('%s: %s' % (self.sName, self.o,));
543	return False;
544	try:
545	# Very noisy -- only enable for debugging purposes.
546	#reporter.log2('%s: op=%u/%u/%s: %u%%; total=%u%% cancel=%s/%s compl=%s rem=%us; desc=%s' \
547	# % (self.sName, iOp, cOps, sOpDesc, iOpPct, iPct, fCanceled, fCancelable, fCompleted, \
548	# cSecsRemain, sDesc));
549	_ = iPct; _ = sDesc; _ = fCancelable; _ = cSecsRemain; _ = fCanceled; _ = fCompleted; _ = iOp;
550	_ = cOps; _ = iOpPct; _ = sOpDesc;
551	except:
552	reporter.errorXcpt();
553	return False;
554
555	return True;
556
557
558	class SessionWrapper(TdTaskBase):
559	"""
560	Wrapper around a machine session. The real session object can be accessed
561	thru the o member (short is good, right :-).
562	"""
563
564	def __init__(self, oSession, oVM, oVBox, oVBoxMgr, oTstDrv, fRemoteSession, sFallbackName = None, sLogFile = None):
565	"""
566	Initializes the session wrapper.
567	"""
568	TdTaskBase.__init__(self, utils.getCallerName());
569	self.o = oSession;
570	self.oVBox = oVBox;
571	self.oVBoxMgr = oVBoxMgr;
572	self.oVM = oVM; # Not the session machine. Useful backdoor...
573	self.oTstDrv = oTstDrv;
574	self.fpApiVer = oTstDrv.fpApiVer;
575	self.fRemoteSession = fRemoteSession;
576	self.sLogFile = sLogFile;
577	self.oConsoleEventHandler = None;
578	self.uPid = None;
579	self.fPidFile = True;
580	self.fHostMemoryLow = False; # see signalHostMemoryLow; read-only for outsiders.
581
582	try:
583	self.sName = oSession.machine.name;
584	except:
585	if sFallbackName is not None:
586	self.sName = sFallbackName;
587	else:
588	try: self.sName = str(oSession.machine);
589	except: self.sName = 'is-this-vm-already-off'
590
591	try:
592	self.sUuid = oSession.machine.id;
593	except:
594	self.sUuid = None;
595
596	# Try cache the SessionPID.
597	self.getPid();
598
599	def __del__(self):
600	"""
601	Destructor that makes sure the callbacks are deregistered and
602	that the session is closed.
603	"""
604	self.deregisterEventHandlerForTask();
605
606	if self.o is not None:
607	try:
608	self.close();
609	reporter.log('close session %s' % (self.o));
610	except:
611	pass;
612	self.o = None;
613
614	TdTaskBase.__del__(self);
615
616	def toString(self):
617	return '<%s: sUuid=%s, sName=%s, uPid=%s, sDbgCreated=%s, fRemoteSession=%s, oSession=%s,' \
618	' oConsoleEventHandler=%s, oVM=%s >' \
619	% (type(self).__name__, self.sUuid, self.sName, self.uPid, self.sDbgCreated, self.fRemoteSession,
620	self.o, self.oConsoleEventHandler, self.oVM,);
621
622	def __str__(self):
623	return self.toString();
624
625	#
626	# TdTaskBase overrides.
627	#
628
629	def __pollTask(self):
630	""" Internal poller """
631	# Poll for events after doing the remote GetState call, otherwise we
632	# might end up sleepless because XPCOM queues a cleanup event.
633	try:
634	try:
635	eState = self.o.machine.state;
636	except Exception as oXcpt:
637	if vbox.ComError.notEqual(oXcpt, vbox.ComError.E_UNEXPECTED):
638	reporter.logXcpt();
639	return True;
640	finally:
641	self.oTstDrv.processPendingEvents();
642
643	# Switch
644	if eState == vboxcon.MachineState_Running:
645	return False;
646	if eState == vboxcon.MachineState_Paused:
647	return False;
648	if eState == vboxcon.MachineState_Teleporting:
649	return False;
650	if eState == vboxcon.MachineState_LiveSnapshotting:
651	return False;
652	if eState == vboxcon.MachineState_Starting:
653	return False;
654	if eState == vboxcon.MachineState_Stopping:
655	return False;
656	if eState == vboxcon.MachineState_Saving:
657	return False;
658	if eState == vboxcon.MachineState_Restoring:
659	return False;
660	if eState == vboxcon.MachineState_TeleportingPausedVM:
661	return False;
662	if eState == vboxcon.MachineState_TeleportingIn:
663	return False;
664
665	# Beeep fudge!
666	if self.fpApiVer < 3.2 \
667	and eState == vboxcon.MachineState_PoweredOff \
668	and self.getAgeAsMs() < 3000:
669	return False;
670
671	reporter.log('SessionWrapper::pollTask: eState=%s' % (eState));
672	return True;
673
674
675	def pollTask(self, fLocked = False):
676	"""
677	Overrides TdTaskBase.pollTask().
678
679	This method returns False while the VM is online and running normally.
680	"""
681
682	# Call super to check if the task was signalled by runtime error or similar,
683	# if not then check the VM state via __pollTask.
684	fRc = super(SessionWrapper, self).pollTask(fLocked);
685	if not fRc:
686	fRc = self.__pollTask();
687
688	# HACK ALERT: Lazily try registering the console event handler if
689	# we're not ready.
690	if not fRc and self.oConsoleEventHandler is None:
691	self.registerEventHandlerForTask();
692
693	# HACK ALERT: Lazily try get the PID and add it to the PID file.
694	if not fRc and self.uPid is None:
695	self.getPid();
696
697	return fRc;
698
699	def waitForTask(self, cMsTimeout = 0):
700	"""
701	Overrides TdTaskBase.waitForTask().
702	Process XPCOM/COM events while waiting.
703	"""
704	msStart = base.timestampMilli();
705	fState = self.pollTask(False);
706	while not fState:
707	cMsElapsed = base.timestampMilli() - msStart;
708	if cMsElapsed > cMsTimeout:
709	break;
710	cMsSleep = cMsTimeout - cMsElapsed;
711	cMsSleep = min(cMsSleep, 10000);
712	try: self.oVBoxMgr.waitForEvents(cMsSleep);
713	except KeyboardInterrupt: raise;
714	except: pass;
715	if self.fnProcessEvents:
716	self.fnProcessEvents();
717	reporter.doPollWork('SessionWrapper.waitForTask');
718	fState = self.pollTask(False);
719	return fState;
720
721	def setTaskOwner(self, oOwner):
722	"""
723	HACK ALERT!
724	Overrides TdTaskBase.setTaskOwner() so we can try call
725	registerEventHandlerForTask() again when when the testdriver calls
726	addTask() after VM has been spawned. Related to pollTask() above.
727
728	The testdriver must not add the task too early for this to work!
729	"""
730	if oOwner is not None:
731	self.registerEventHandlerForTask()
732	return TdTaskBase.setTaskOwner(self, oOwner);
733
734
735	#
736	# Task helpers.
737	#
738
739	def registerEventHandlerForTask(self):
740	"""
741	Registers the console event handlers for working the task state.
742	"""
743	if self.oConsoleEventHandler is not None:
744	return True;
745	self.oConsoleEventHandler = self.registerDerivedEventHandler(vbox.SessionConsoleEventHandler, {}, False);
746	return self.oConsoleEventHandler is not None;
747
748	def deregisterEventHandlerForTask(self):
749	"""
750	Deregisters the console event handlers.
751	"""
752	if self.oConsoleEventHandler is not None:
753	self.oConsoleEventHandler.unregister();
754	self.oConsoleEventHandler = None;
755
756	def signalHostMemoryLow(self):
757	"""
758	Used by a runtime error event handler to indicate that we're low on memory.
759	Signals the task.
760	"""
761	self.fHostMemoryLow = True;
762	self.signalTask();
763	return True;
764
765	def needsPoweringOff(self):
766	"""
767	Examins the machine state to see if the VM needs powering off.
768	"""
769	try:
770	try:
771	eState = self.o.machine.state;
772	except Exception as oXcpt:
773	if vbox.ComError.notEqual(oXcpt, vbox.ComError.E_UNEXPECTED):
774	reporter.logXcpt();
775	return False;
776	finally:
777	self.oTstDrv.processPendingEvents();
778
779	# Switch
780	if eState == vboxcon.MachineState_Running:
781	return True;
782	if eState == vboxcon.MachineState_Paused:
783	return True;
784	if eState == vboxcon.MachineState_Stuck:
785	return True;
786	if eState == vboxcon.MachineState_Teleporting:
787	return True;
788	if eState == vboxcon.MachineState_LiveSnapshotting:
789	return True;
790	if eState == vboxcon.MachineState_Starting:
791	return True;
792	if eState == vboxcon.MachineState_Saving:
793	return True;
794	if eState == vboxcon.MachineState_Restoring:
795	return True;
796	if eState == vboxcon.MachineState_TeleportingPausedVM:
797	return True;
798	if eState == vboxcon.MachineState_TeleportingIn:
799	return True;
800	if hasattr(vboxcon, 'MachineState_FaultTolerantSyncing'):
801	if eState == vboxcon.MachineState_FaultTolerantSyncing:
802	return True;
803	return False;
804
805	def assertPoweredOff(self):
806	"""
807	Asserts that the VM is powered off, reporting an error if not.
808	Returns True if powered off, False + error msg if not.
809	"""
810	try:
811	try:
812	eState = self.oVM.state;
813	except Exception:
814	reporter.errorXcpt();
815	return True;
816	finally:
817	self.oTstDrv.processPendingEvents();
818
819	if eState == vboxcon.MachineState_PoweredOff:
820	return True;
821	reporter.error('Expected machine state "PoweredOff", machine is in the "%s" state instead.'
822	% (_nameMachineState(eState),));
823	return False;
824
825	def getMachineStateWithName(self):
826	"""
827	Gets the current machine state both as a constant number/whatever and
828	as a human readable string. On error, the constants will be set to
829	None and the string will be the error message.
830	"""
831	try:
832	eState = self.oVM.state;
833	except:
834	return (None, '[error getting state: %s]' % (self.oVBoxMgr.xcptToString(),));
835	finally:
836	self.oTstDrv.processPendingEvents();
837	return (eState, _nameMachineState(eState));
838
839	def reportPrematureTermination(self, sPrefix = ''):
840	"""
841	Reports a premature virtual machine termination.
842	Returns False to facilitate simpler error paths.
843	"""
844
845	reporter.error(sPrefix + 'The virtual machine terminated prematurely!!');
846	(enmState, sStateNm) = self.getMachineStateWithName();
847	reporter.error(sPrefix + 'Machine state: %s' % (sStateNm,));
848
849	if enmState is not None \
850	and enmState == vboxcon.MachineState_Aborted \
851	and self.uPid is not None:
852	#
853	# Look for process crash info.
854	#
855	def addCrashFile(sLogFile, fBinary):
856	""" processCollectCrashInfo callback. """
857	reporter.addLogFile(sLogFile, 'crash/dump/vm' if fBinary else 'crash/report/vm');
858	utils.processCollectCrashInfo(self.uPid, reporter.log, addCrashFile);
859
860	return False;
861
862
863
864	#
865	# ISession / IMachine / ISomethingOrAnother wrappers.
866	#
867
868	def close(self):
869	"""
870	Closes the session if it's open and removes it from the
871	vbox.TestDriver.aoRemoteSessions list.
872	Returns success indicator.
873	"""
874	fRc = True;
875	if self.o is not None:
876	# Get the pid in case we need to kill the process later on.
877	self.getPid();
878
879	# Try close it.
880	try:
881	if self.fpApiVer < 3.3:
882	self.o.close();
883	else:
884	self.o.unlockMachine();
885	self.o = None;
886	except KeyboardInterrupt:
887	raise;
888	except:
889	# Kludge to ignore VBoxSVC's closing of our session when the
890	# direct session closes / VM process terminates. Fun!
891	try: fIgnore = self.o.state == vboxcon.SessionState_Unlocked;
892	except: fIgnore = False;
893	if fIgnore:
894	self.o = None; # Must prevent a retry during GC.
895	else:
896	reporter.errorXcpt('ISession::unlockMachine failed on %s' % (self.o));
897	fRc = False;
898
899	# Remove it from the remote session list if applicable (not 100% clean).
900	if fRc and self.fRemoteSession:
901	try:
902	if self in self.oTstDrv.aoRemoteSessions:
903	reporter.log2('SessionWrapper::close: Removing myself from oTstDrv.aoRemoteSessions');
904	self.oTstDrv.aoRemoteSessions.remove(self)
905	except:
906	reporter.logXcpt();
907
908	if self.uPid is not None and self.fPidFile:
909	self.oTstDrv.pidFileRemove(self.uPid);
910	self.fPidFile = False;
911
912	# It's only logical to deregister the event handler after the session
913	# is closed. It also avoids circular references between the session
914	# and the listener, which causes trouble with garbage collection.
915	self.deregisterEventHandlerForTask();
916
917	self.oTstDrv.processPendingEvents();
918	return fRc;
919
920	def saveSettings(self, fClose = False):
921	"""
922	Saves the settings and optionally closes the session.
923	Returns success indicator.
924	"""
925	try:
926	try:
927	self.o.machine.saveSettings();
928	except:
929	reporter.errorXcpt('saveSettings failed on %s' % (self.o));
930	return False;
931	finally:
932	self.oTstDrv.processPendingEvents();
933	if fClose:
934	return self.close();
935	return True;
936
937	def discardSettings(self, fClose = False):
938	"""
939	Discards the settings and optionally closes the session.
940	"""
941	try:
942	try:
943	self.o.machine.discardSettings();
944	except:
945	reporter.errorXcpt('discardSettings failed on %s' % (self.o));
946	return False;
947	finally:
948	self.oTstDrv.processPendingEvents();
949	if fClose:
950	return self.close();
951	return True;
952
953	def isPlatformArch(self, enmPlatformArch):
954	"""
955	Returns if the machine is of the given platform architecture or not.
956	"""
957	if not self.o:
958	return False;
959	if self.fpApiVer >= 7.1:
960	return self.o.machine.platform.architecture == enmPlatformArch;
961	return enmPlatformArch == vboxcon.PlatformArchitecture_x86; # VBox < 7.1 only supported x86.
962
963	def isPlatformARM(self):
964	"""
965	Returns if the machine is of the ARM platform architecture or not.
966	"""
967	if self.fpApiVer >= 7.1:
968	return self.isPlatformArch(vboxcon.PlatformArchitecture_ARM);
969	return False; # For VBox < 7.1 this always is false (x86 only).
970
971	def isPlatformX86(self):
972	"""
973	Returns if the machine is of the x86 platform architecture or not.
974	"""
975	if self.fpApiVer >= 7.1:
976	return self.isPlatformArch(vboxcon.PlatformArchitecture_x86);
977	return True; # For VBox < 7.1 this always is true (x86 only).
978
979	def enableVirtExX86(self, fEnable):
980	"""
981	Enables or disables AMD-V/VT-x. x86 only.
982	Returns True on success and False on failure. Error information is logged.
983
984	Ignored on non-x86 platform architectures.
985	"""
986	if not self.isPlatformX86(): return True;
987	# Enable/disable it.
988	fRc = True;
989	try:
990	if self.fpApiVer >= 7.1:
991	self.o.machine.platform.x86.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_Enabled, fEnable);
992	else:
993	self.o.machine.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_Enabled, fEnable);
994	except:
995	reporter.errorXcpt('failed to set HWVirtExPropertyType_Enabled=%s for "%s"' % (fEnable, self.sName));
996	fRc = False;
997	else:
998	reporter.log('set HWVirtExPropertyType_Enabled=%s for "%s"' % (fEnable, self.sName));
999
1000	# Force/unforce it.
1001	if fRc and hasattr(vboxcon, 'HWVirtExPropertyType_Force'):
1002	try:
1003	if self.fpApiVer >= 7.1:
1004	self.o.machine.platform.x86.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_Force, fEnable);
1005	else:
1006	self.o.machine.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_Force, fEnable);
1007	except:
1008	reporter.errorXcpt('failed to set HWVirtExPropertyType_Force=%s for "%s"' % (fEnable, self.sName));
1009	fRc = False;
1010	else:
1011	reporter.log('set HWVirtExPropertyType_Force=%s for "%s"' % (fEnable, self.sName));
1012	else:
1013	reporter.log('Warning! vboxcon has no HWVirtExPropertyType_Force attribute.');
1014	## @todo Modify CFGM to do the same for old VBox versions?
1015
1016	self.oTstDrv.processPendingEvents();
1017	return fRc;
1018
1019	def enableNestedPagingX86(self, fEnable):
1020	"""
1021	Enables or disables nested paging. x86 only.
1022	Returns True on success and False on failure. Error information is logged.
1023
1024	Ignored on non-x86 platform architectures.
1025	"""
1026	if not self.isPlatformX86(): return True;
1027	## @todo Add/remove force CFGM thing, we don't want fallback logic when testing.
1028	fRc = True;
1029	try:
1030	if self.fpApiVer >= 7.1:
1031	self.o.machine.platform.x86.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_NestedPaging, fEnable);
1032	else:
1033	self.o.machine.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_NestedPaging, fEnable);
1034	except:
1035	reporter.errorXcpt('failed to set HWVirtExPropertyType_NestedPaging=%s for "%s"' % (fEnable, self.sName));
1036	fRc = False;
1037	else:
1038	reporter.log('set HWVirtExPropertyType_NestedPaging=%s for "%s"' % (fEnable, self.sName));
1039	self.oTstDrv.processPendingEvents();
1040	return fRc;
1041
1042	def enableLongModeX86(self, fEnable):
1043	"""
1044	Enables or disables LongMode. x86 only.
1045	Returns True on success and False on failure. Error information is logged.
1046
1047	Ignored on non-x86 platform architectures.
1048	"""
1049	if not self.isPlatformX86(): return True;
1050	# Supported.
1051	if self.fpApiVer < 4.2 or not hasattr(vboxcon, 'HWVirtExPropertyType_LongMode'):
1052	return True;
1053
1054	# Enable/disable it.
1055	fRc = True;
1056	try:
1057	if self.fpApiVer >= 7.1:
1058	self.o.machine.platform.x86.setCPUProperty(vboxcon.CPUPropertyTypeX86_LongMode, fEnable);
1059	else:
1060	self.o.machine.setCPUProperty(vboxcon.CPUPropertyType_LongMode, fEnable);
1061	except:
1062	reporter.errorXcpt('failed to set CPUPropertyType_LongMode=%s for "%s"' % (fEnable, self.sName));
1063	fRc = False;
1064	else:
1065	reporter.log('set CPUPropertyType_LongMode=%s for "%s"' % (fEnable, self.sName));
1066	self.oTstDrv.processPendingEvents();
1067	return fRc;
1068
1069	def enableNestedHwVirtX86(self, fEnable):
1070	"""
1071	Enables or disables Nested Hardware-Virtualization. x86 only.
1072	Returns True on success and False on failure. Error information is logged.
1073
1074	Ignored on non-x86 platform architectures.
1075	"""
1076	if not self.isPlatformX86(): return True;
1077	# Supported.
1078	if self.fpApiVer < 5.3:
1079	return True;
1080	if self.fpApiVer < 7.1 and not hasattr(vboxcon, 'CPUPropertyType_HWVirt'):
1081	return True;
1082	if self.fpApiVer >= 7.1 and not hasattr(vboxcon, 'CPUPropertyTypeX86_HWVirt'):
1083	return True;
1084
1085	# Enable/disable it.
1086	fRc = True;
1087	try:
1088	if self.fpApiVer >= 7.1:
1089	self.o.machine.platform.x86.setCPUProperty(vboxcon.CPUPropertyTypeX86_HWVirt, fEnable);
1090	else:
1091	self.o.machine.setCPUProperty(vboxcon.CPUPropertyType_HWVirt, fEnable);
1092	except:
1093	reporter.errorXcpt('failed to set CPUPropertyType_HWVirt=%s for "%s"' % (fEnable, self.sName));
1094	fRc = False;
1095	else:
1096	reporter.log('set CPUPropertyType_HWVirt=%s for "%s"' % (fEnable, self.sName));
1097	self.oTstDrv.processPendingEvents();
1098	return fRc;
1099
1100	def enablePaeX86(self, fEnable):
1101	"""
1102	Enables or disables PAE. x86 only.
1103	Returns True on success and False on failure. Error information is logged.
1104
1105	Ignored on non-x86 platform architectures.
1106	"""
1107	if not self.isPlatformX86(): return True;
1108	fRc = True;
1109	try:
1110	if self.fpApiVer >= 7.1:
1111	self.o.machine.platform.x86.setCPUProperty(vboxcon.CPUPropertyTypeX86_PAE, fEnable);
1112	elif self.fpApiVer >= 3.2: # great, ain't it?
1113	self.o.machine.setCPUProperty(vboxcon.CPUPropertyType_PAE, fEnable);
1114	else:
1115	self.o.machine.setCpuProperty(vboxcon.CpuPropertyType_PAE, fEnable);
1116	except:
1117	reporter.errorXcpt('failed to set CPUPropertyType_PAE=%s for "%s"' % (fEnable, self.sName));
1118	fRc = False;
1119	else:
1120	reporter.log('set CPUPropertyType_PAE=%s for "%s"' % (fEnable, self.sName));
1121	self.oTstDrv.processPendingEvents();
1122	return fRc;
1123
1124	def enableIoApic(self, fEnable):
1125	"""
1126	Enables or disables the IO-APIC.
1127	Returns True on success and False on failure. Error information is logged.
1128	"""
1129	fRc = True;
1130	try:
1131	if self.fpApiVer >= 7.1:
1132	self.o.machine.firmwareSettings.IOAPICEnabled = fEnable;
1133	else:
1134	self.o.machine.BIOSSettings.IOAPICEnabled = fEnable;
1135	except:
1136	reporter.errorXcpt('failed to set firmwareSettings.IOAPICEnabled=%s for "%s"' % (fEnable, self.sName));
1137	fRc = False;
1138	else:
1139	reporter.log('set firmwareSettings.IOAPICEnabled=%s for "%s"' % (fEnable, self.sName));
1140	self.oTstDrv.processPendingEvents();
1141	return fRc;
1142
1143	def enableHpetX86(self, fEnable):
1144	"""
1145	Enables or disables the HPET. x86 only.
1146	Returns True on success and False on failure. Error information is logged.
1147
1148	Ignored on non-x86 platform architectures.
1149	"""
1150	if not self.isPlatformX86(): return True;
1151	fRc = True;
1152	try:
1153	if self.fpApiVer >= 7.1:
1154	self.o.machine.platform.x86.HPETEnabled = fEnable;
1155	elif self.fpApiVer >= 4.2:
1156	self.o.machine.HPETEnabled = fEnable;
1157	else:
1158	self.o.machine.hpetEnabled = fEnable;
1159	except:
1160	reporter.errorXcpt('failed to set HpetEnabled=%s for "%s"' % (fEnable, self.sName));
1161	fRc = False;
1162	else:
1163	reporter.log('set HpetEnabled=%s for "%s"' % (fEnable, self.sName));
1164	self.oTstDrv.processPendingEvents();
1165	return fRc;
1166
1167	def enableUsbHid(self, fEnable):
1168	"""
1169	Enables or disables the USB HID.
1170	Returns True on success and False on failure. Error information is logged.
1171	"""
1172	fRc = True;
1173	try:
1174	if fEnable:
1175	if self.fpApiVer >= 4.3:
1176	cOhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_OHCI);
1177	if cOhciCtls == 0:
1178	self.o.machine.addUSBController('OHCI', vboxcon.USBControllerType_OHCI);
1179	else:
1180	self.o.machine.usbController.enabled = True;
1181
1182	if self.fpApiVer >= 4.2:
1183	self.o.machine.pointingHIDType = vboxcon.PointingHIDType_ComboMouse;
1184	self.o.machine.keyboardHIDType = vboxcon.KeyboardHIDType_ComboKeyboard;
1185	else:
1186	self.o.machine.pointingHidType = vboxcon.PointingHidType_ComboMouse;
1187	self.o.machine.keyboardHidType = vboxcon.KeyboardHidType_ComboKeyboard;
1188	else:
1189	if self.fpApiVer >= 4.2:
1190	self.o.machine.pointingHIDType = vboxcon.PointingHIDType_PS2Mouse;
1191	self.o.machine.keyboardHIDType = vboxcon.KeyboardHIDType_PS2Keyboard;
1192	else:
1193	self.o.machine.pointingHidType = vboxcon.PointingHidType_PS2Mouse;
1194	self.o.machine.keyboardHidType = vboxcon.KeyboardHidType_PS2Keyboard;
1195	except:
1196	reporter.errorXcpt('failed to change UsbHid to %s for "%s"' % (fEnable, self.sName));
1197	fRc = False;
1198	else:
1199	reporter.log('changed UsbHid to %s for "%s"' % (fEnable, self.sName));
1200	self.oTstDrv.processPendingEvents();
1201	return fRc;
1202
1203	def enableUsbOhci(self, fEnable):
1204	"""
1205	Enables or disables the USB OHCI controller.
1206	Returns True on success and False on failure. Error information is logged.
1207	"""
1208	fRc = True;
1209	try:
1210	if fEnable:
1211	if self.fpApiVer >= 4.3:
1212	cOhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_OHCI);
1213	if cOhciCtls == 0:
1214	self.o.machine.addUSBController('OHCI', vboxcon.USBControllerType_OHCI);
1215	else:
1216	self.o.machine.usbController.enabled = True;
1217	else:
1218	if self.fpApiVer >= 4.3:
1219	cOhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_OHCI);
1220	if cOhciCtls == 1:
1221	self.o.machine.removeUSBController('OHCI');
1222	else:
1223	self.o.machine.usbController.enabled = False;
1224	except:
1225	reporter.errorXcpt('failed to change OHCI to %s for "%s"' % (fEnable, self.sName));
1226	fRc = False;
1227	else:
1228	reporter.log('changed OHCI to %s for "%s"' % (fEnable, self.sName));
1229	self.oTstDrv.processPendingEvents();
1230	return fRc;
1231
1232	def enableUsbEhci(self, fEnable):
1233	"""
1234	Enables or disables the USB EHCI controller, enables also OHCI if it is still disabled.
1235	Returns True on success and False on failure. Error information is logged.
1236	"""
1237	fRc = True;
1238	try:
1239	if fEnable:
1240	if self.fpApiVer >= 4.3:
1241	cOhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_OHCI);
1242	if cOhciCtls == 0:
1243	self.o.machine.addUSBController('OHCI', vboxcon.USBControllerType_OHCI);
1244
1245	cEhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_EHCI);
1246	if cEhciCtls == 0:
1247	self.o.machine.addUSBController('EHCI', vboxcon.USBControllerType_EHCI);
1248	else:
1249	self.o.machine.usbController.enabled = True;
1250	self.o.machine.usbController.enabledEHCI = True;
1251	else:
1252	if self.fpApiVer >= 4.3:
1253	cEhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_EHCI);
1254	if cEhciCtls == 1:
1255	self.o.machine.removeUSBController('EHCI');
1256	else:
1257	self.o.machine.usbController.enabledEHCI = False;
1258	except:
1259	reporter.errorXcpt('failed to change EHCI to %s for "%s"' % (fEnable, self.sName));
1260	fRc = False;
1261	else:
1262	reporter.log('changed EHCI to %s for "%s"' % (fEnable, self.sName));
1263	self.oTstDrv.processPendingEvents();
1264	return fRc;
1265
1266	def enableUsbXhci(self, fEnable):
1267	"""
1268	Enables or disables the USB XHCI controller. Error information is logged.
1269	"""
1270	fRc = True;
1271	try:
1272	if fEnable:
1273	cXhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_XHCI);
1274	if cXhciCtls == 0:
1275	self.o.machine.addUSBController('XHCI', vboxcon.USBControllerType_XHCI);
1276	else:
1277	cXhciCtls = self.o.machine.getUSBControllerCountByType(vboxcon.USBControllerType_XHCI);
1278	if cXhciCtls == 1:
1279	self.o.machine.removeUSBController('XHCI');
1280	except:
1281	reporter.errorXcpt('failed to change XHCI to %s for "%s"' % (fEnable, self.sName));
1282	fRc = False;
1283	else:
1284	reporter.log('changed XHCI to %s for "%s"' % (fEnable, self.sName));
1285	self.oTstDrv.processPendingEvents();
1286	return fRc;
1287
1288	def setFirmwareType(self, eType):
1289	"""
1290	Sets the firmware type.
1291	Returns True on success and False on failure. Error information is logged.
1292	"""
1293	fRc = True;
1294	try:
1295	if self.fpApiVer >= 7.1:
1296	self.o.machine.firmwareSettings.firmwareType = eType;
1297	else:
1298	self.o.machine.firmwareType = eType;
1299	except:
1300	reporter.errorXcpt('failed to set firmwareType=%s for "%s"' % (eType, self.sName));
1301	fRc = False;
1302	else:
1303	reporter.log('set firmwareType=%s for "%s"' % (eType, self.sName));
1304	self.oTstDrv.processPendingEvents();
1305	return fRc;
1306
1307	def enableSecureBoot(self, fEnable, sUefiMokPathPrefix = None):
1308	"""
1309	Enables or disables Secure Boot. Error information is logged.
1310	"""
1311
1312	if self.fpApiVer >= 7.0:
1313
1314	fRc = True;
1315	try:
1316	self.o.machine.nonVolatileStore.initUefiVariableStore(0);
1317
1318	# Enroll necessary keys and signatures in case if Secure Boot needs to be turned ON.
1319	if fEnable:
1320	self.o.machine.nonVolatileStore.uefiVariableStore.enrollDefaultMsSignatures();
1321	self.o.machine.nonVolatileStore.uefiVariableStore.enrollOraclePlatformKey();
1322	if sUefiMokPathPrefix:
1323	if self.oTstDrv.uRevision >= 156564: # Backported IUefiVariableStore::addSignatureToMok() to 7.0.
1324	sFullName = self.oTstDrv.getFullResourceName(sUefiMokPathPrefix) + '.der';
1325	with open(sFullName, "rb") as der_file:
1326	self.o.machine.nonVolatileStore.uefiVariableStore.addSignatureToMok(bytearray(der_file.read()), \
1327	uuid.uuid4().hex, \
1328	vboxcon.SignatureType_X509);
1329	else:
1330	reporter.log('Warning: Enrolling own keys / signatures only available for 7.0 >= r156564. ' \
1331	'Guest Additions installation might fail!');
1332
1333	self.o.machine.nonVolatileStore.uefiVariableStore.secureBootEnabled = fEnable;
1334	except:
1335	reporter.errorXcpt('failed to change Secure Boot to %s for "%s"' % (fEnable, self.sName));
1336	fRc = False;
1337	else:
1338	reporter.log('changed Secure Boot to %s for "%s"' % (fEnable, self.sName));
1339	self.oTstDrv.processPendingEvents();
1340
1341	else:
1342	reporter.log('Secure Boot is only supported for API 7.0 or newer');
1343	fRc = False;
1344
1345	return fRc;
1346
1347	def setChipsetType(self, eType):
1348	"""
1349	Sets the chipset type.
1350	Returns True on success and False on failure. Error information is logged.
1351	"""
1352	fRc = True;
1353	try:
1354	if self.fpApiVer >= 7.1:
1355	self.o.machine.platform.chipsetType = eType;
1356	else:
1357	self.o.machine.chipsetType = eType;
1358	except:
1359	reporter.errorXcpt('failed to set chipsetType=%s for "%s"' % (eType, self.sName));
1360	fRc = False;
1361	else:
1362	reporter.log('set chipsetType=%s for "%s"' % (eType, self.sName));
1363	self.oTstDrv.processPendingEvents();
1364	return fRc;
1365
1366	def setIommuType(self, eType):
1367	"""
1368	Sets the IOMMU type.
1369	Returns True on success and False on failure. Error information is logged.
1370	"""
1371	# Supported.
1372	if self.fpApiVer < 6.2 or not hasattr(vboxcon, 'IommuType_Intel') or not hasattr(vboxcon, 'IommuType_AMD'):
1373	return True;
1374	fRc = True;
1375	try:
1376	if self.fpApiVer >= 7.1:
1377	self.o.machine.platform.iommuType = eType;
1378	else:
1379	self.o.machine.iommuType = eType;
1380	except:
1381	reporter.errorXcpt('failed to set iommuType=%s for "%s"' % (eType, self.sName));
1382	fRc = False;
1383	else:
1384	reporter.log('set iommuType=%s for "%s"' % (eType, self.sName));
1385	self.oTstDrv.processPendingEvents();
1386	return fRc;
1387
1388	def setupBootLogo(self, fEnable, cMsLogoDisplay = 0):
1389	"""
1390	Sets up the boot logo. fEnable toggles the fade and boot menu
1391	settings as well as the mode.
1392	"""
1393	fRc = True;
1394	try:
1395	if self.fpApiVer >= 7.1:
1396	fwSettings = self.o.machine.firmwareSettings;
1397	if fEnable:
1398	fwSettings.bootMenuMode = vboxcon.FirmwareBootMenuMode_Disabled;
1399	else:
1400	fwSettings.bootMenuMode = vboxcon.FirmwareBootMenuMode_MessageAndMenu;
1401	else:
1402	fwSettings = self.o.machine.BIOSSettings;
1403	if fEnable:
1404	fwSettings.bootMenuMode = vboxcon.BIOSBootMenuMode_Disabled;
1405	else:
1406	fwSettings.bootMenuMode = vboxcon.BIOSBootMenuMode_MessageAndMenu;
1407	fwSettings.logoFadeIn = not fEnable;
1408	fwSettings.logoFadeOut = not fEnable;
1409	fwSettings.logoDisplayTime = cMsLogoDisplay;
1410	except:
1411	reporter.errorXcpt('failed to set logoFadeIn/logoFadeOut/bootMenuMode=%s for "%s"' % (fEnable, self.sName));
1412	fRc = False;
1413	else:
1414	reporter.log('set logoFadeIn/logoFadeOut/bootMenuMode=%s for "%s"' % (fEnable, self.sName));
1415	self.oTstDrv.processPendingEvents();
1416	return fRc;
1417
1418	def setupVrdp(self, fEnable, uPort = None):
1419	"""
1420	Configures VRDP.
1421	"""
1422	fRc = True;
1423	try:
1424	if self.fpApiVer >= 4.0:
1425	self.o.machine.VRDEServer.enabled = fEnable;
1426	else:
1427	self.o.machine.VRDPServer.enabled = fEnable;
1428	except:
1429	reporter.errorXcpt('failed to set VRDEServer::enabled=%s for "%s"' % (fEnable, self.sName));
1430	fRc = False;
1431
1432	if uPort is not None and fRc:
1433	try:
1434	if self.fpApiVer >= 4.0:
1435	self.o.machine.VRDEServer.setVRDEProperty("TCP/Ports", str(uPort));
1436	else:
1437	self.o.machine.VRDPServer.ports = str(uPort);
1438	except:
1439	reporter.errorXcpt('failed to set VRDEServer::ports=%s for "%s"' % (uPort, self.sName));
1440	fRc = False;
1441	if fRc:
1442	reporter.log('set VRDEServer.enabled/ports=%s/%s for "%s"' % (fEnable, uPort, self.sName));
1443	self.oTstDrv.processPendingEvents();
1444	return fRc;
1445
1446	def getNicDriverNameFromType(self, eNicType):
1447	"""
1448	Helper that translate the adapter type into a driver name.
1449	"""
1450	if eNicType in (vboxcon.NetworkAdapterType_Am79C970A, vboxcon.NetworkAdapterType_Am79C973):
1451	sName = 'pcnet';
1452	elif eNicType in (vboxcon.NetworkAdapterType_I82540EM,
1453	vboxcon.NetworkAdapterType_I82543GC,
1454	vboxcon.NetworkAdapterType_I82545EM):
1455	sName = 'e1000';
1456	elif eNicType == vboxcon.NetworkAdapterType_Virtio:
1457	sName = 'virtio-net';
1458	else:
1459	reporter.error('Unknown adapter type "%s" (VM: "%s")' % (eNicType, self.sName));
1460	sName = 'pcnet';
1461	return sName;
1462
1463	def setupNatForwardingForTxs(self, iNic = 0, iHostPort = 5042):
1464	"""
1465	Sets up NAT forwarding for port 5042 if applicable, cleans up if not.
1466	"""
1467	try:
1468	oNic = self.o.machine.getNetworkAdapter(iNic);
1469	except:
1470	reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName));
1471	return False;
1472
1473	# Nuke the old setup for all possible adapter types (in case we're
1474	# called after it changed).
1475	for sName in ('pcnet', 'e1000', 'virtio-net'):
1476	for sConfig in ('VBoxInternal/Devices/%s/%u/LUN#0/AttachedDriver/Config' % (sName, iNic), \
1477	'VBoxInternal/Devices/%s/%u/LUN#0/Config' % (sName, iNic)):
1478	try:
1479	self.o.machine.setExtraData('%s/txs/Protocol' % (sConfig), '');
1480	self.o.machine.setExtraData('%s/txs/HostPort' % (sConfig), '');
1481	self.o.machine.setExtraData('%s/txs/GuestPort' % (sConfig), '');
1482	except:
1483	reporter.errorXcpt();
1484
1485	# Set up port forwarding if NAT attachment.
1486	try:
1487	eAttType = oNic.attachmentType;
1488	except:
1489	reporter.errorXcpt('attachmentType on %s failed for "%s"' % (iNic, self.sName));
1490	return False;
1491	if eAttType != vboxcon.NetworkAttachmentType_NAT:
1492	return True;
1493
1494	try:
1495	eNicType = oNic.adapterType;
1496	fTraceEnabled = oNic.traceEnabled;
1497	except:
1498	reporter.errorXcpt('attachmentType/traceEnabled on %s failed for "%s"' % (iNic, self.sName));
1499	return False;
1500
1501	if self.fpApiVer >= 4.1:
1502	try:
1503	if self.fpApiVer >= 4.2:
1504	oNatEngine = oNic.NATEngine;
1505	else:
1506	oNatEngine = oNic.natDriver;
1507	except:
1508	reporter.errorXcpt('Failed to get INATEngine data on "%s"' % (self.sName));
1509	return False;
1510	try: oNatEngine.removeRedirect('txs');
1511	except: pass;
1512	try:
1513	oNatEngine.addRedirect('txs', vboxcon.NATProtocol_TCP, '127.0.0.1', '%s' % (iHostPort), '', '5042');
1514	except:
1515	reporter.errorXcpt('Failed to add a addRedirect redirect on "%s"' % (self.sName));
1516	return False;
1517
1518	else:
1519	sName = self.getNicDriverNameFromType(eNicType);
1520	if fTraceEnabled:
1521	sConfig = 'VBoxInternal/Devices/%s/%u/LUN#0/AttachedDriver/Config' % (sName, iNic)
1522	else:
1523	sConfig = 'VBoxInternal/Devices/%s/%u/LUN#0/Config' % (sName, iNic)
1524
1525	try:
1526	self.o.machine.setExtraData('%s/txs/Protocol' % (sConfig), 'TCP');
1527	self.o.machine.setExtraData('%s/txs/HostPort' % (sConfig), '%s' % (iHostPort));
1528	self.o.machine.setExtraData('%s/txs/GuestPort' % (sConfig), '5042');
1529	except:
1530	reporter.errorXcpt('Failed to set NAT extra data on "%s"' % (self.sName));
1531	return False;
1532	return True;
1533
1534	def setNicType(self, eType, iNic = 0):
1535	"""
1536	Sets the NIC type of the specified NIC.
1537	Returns True on success and False on failure. Error information is logged.
1538	"""
1539	try:
1540	try:
1541	oNic = self.o.machine.getNetworkAdapter(iNic);
1542	except:
1543	reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName));
1544	return False;
1545	try:
1546	oNic.adapterType = eType;
1547	except:
1548	reporter.errorXcpt('failed to set NIC type on slot %s to %s for VM "%s"' % (iNic, eType, self.sName));
1549	return False;
1550	finally:
1551	self.oTstDrv.processPendingEvents();
1552
1553	if not self.setupNatForwardingForTxs(iNic):
1554	return False;
1555	reporter.log('set NIC type on slot %s to %s for VM "%s"' % (iNic, eType, self.sName));
1556	return True;
1557
1558	def setNicTraceEnabled(self, fTraceEnabled, sTraceFile, iNic = 0):
1559	"""
1560	Sets the NIC trace enabled flag and file path.
1561	Returns True on success and False on failure. Error information is logged.
1562	"""
1563	try:
1564	try:
1565	oNic = self.o.machine.getNetworkAdapter(iNic);
1566	except:
1567	reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName));
1568	return False;
1569	try:
1570	oNic.traceEnabled = fTraceEnabled;
1571	oNic.traceFile = sTraceFile;
1572	except:
1573	reporter.errorXcpt('failed to set NIC trace flag on slot %s to %s for VM "%s"' \
1574	% (iNic, fTraceEnabled, self.sName));
1575	return False;
1576	finally:
1577	self.oTstDrv.processPendingEvents();
1578
1579	if not self.setupNatForwardingForTxs(iNic):
1580	return False;
1581	reporter.log('set NIC trace on slot %s to "%s" (path "%s") for VM "%s"' %
1582	(iNic, fTraceEnabled, sTraceFile, self.sName));
1583	return True;
1584
1585	def getDefaultNicName(self, eAttachmentType):
1586	"""
1587	Return the default network / interface name for the NIC attachment type.
1588	"""
1589	sRetName = '';
1590	if eAttachmentType == vboxcon.NetworkAttachmentType_Bridged:
1591	if self.oTstDrv.sDefBridgedNic is not None:
1592	sRetName = self.oTstDrv.sDefBridgedNic;
1593	else:
1594	sRetName = 'eth0';
1595	try:
1596	aoHostNics = self.oVBoxMgr.getArray(self.oVBox.host, 'networkInterfaces');
1597	for oHostNic in aoHostNics:
1598	if oHostNic.interfaceType == vboxcon.HostNetworkInterfaceType_Bridged \
1599	and oHostNic.status == vboxcon.HostNetworkInterfaceStatus_Up:
1600	sRetName = oHostNic.name;
1601	break;
1602	except:
1603	reporter.errorXcpt();
1604
1605	elif eAttachmentType == vboxcon.NetworkAttachmentType_HostOnly:
1606	try:
1607	aoHostNics = self.oVBoxMgr.getArray(self.oVBox.host, 'networkInterfaces');
1608	for oHostNic in aoHostNics:
1609	if oHostNic.interfaceType == vboxcon.HostNetworkInterfaceType_HostOnly:
1610	if oHostNic.status == vboxcon.HostNetworkInterfaceStatus_Up:
1611	sRetName = oHostNic.name;
1612	break;
1613	if sRetName == '':
1614	sRetName = oHostNic.name;
1615	except:
1616	reporter.errorXcpt();
1617	if sRetName == '':
1618	# Create a new host-only interface.
1619	reporter.log("Creating host only NIC ...");
1620	try:
1621	(oIProgress, oIHostOnly) = self.oVBox.host.createHostOnlyNetworkInterface();
1622	oProgress = ProgressWrapper(oIProgress, self.oVBoxMgr, self.oTstDrv, 'Create host only NIC');
1623	oProgress.wait();
1624	if oProgress.logResult() is False:
1625	return '';
1626	sRetName = oIHostOnly.name;
1627	except:
1628	reporter.errorXcpt();
1629	return '';
1630	reporter.log("Created host only NIC: '%s'" % (sRetName,));
1631
1632	elif self.fpApiVer >= 7.0 and eAttachmentType == vboxcon.NetworkAttachmentType_HostOnlyNetwork:
1633	aoHostNetworks = self.oVBoxMgr.getArray(self.oVBox, 'hostOnlyNetworks');
1634	if aoHostNetworks:
1635	sRetName = aoHostNetworks[0].networkName;
1636	else:
1637	try:
1638	oHostOnlyNet = self.oVBox.createHostOnlyNetwork('Host-only Test Network');
1639	oHostOnlyNet.lowerIP = '192.168.56.1';
1640	oHostOnlyNet.upperIP = '192.168.56.199';
1641	oHostOnlyNet.networkMask = '255.255.255.0';
1642	sRetName = oHostOnlyNet.networkName;
1643	except:
1644	reporter.errorXcpt();
1645	return '';
1646
1647	elif eAttachmentType == vboxcon.NetworkAttachmentType_Internal:
1648	sRetName = 'VBoxTest';
1649
1650	elif eAttachmentType == vboxcon.NetworkAttachmentType_NAT:
1651	sRetName = '';
1652
1653	else: ## @todo Support NetworkAttachmentType_NATNetwork
1654	reporter.error('eAttachmentType=%s is not known' % (eAttachmentType));
1655	return sRetName;
1656
1657	def setNicAttachment(self, eAttachmentType, sName = None, iNic = 0):
1658	"""
1659	Sets the attachment type of the specified NIC.
1660	Returns True on success and False on failure. Error information is logged.
1661	"""
1662	try:
1663	oNic = self.o.machine.getNetworkAdapter(iNic);
1664	except:
1665	reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName));
1666	return False;
1667
1668	try:
1669	if eAttachmentType is not None:
1670	try:
1671	if self.fpApiVer >= 4.1:
1672	oNic.attachmentType = eAttachmentType;
1673	else:
1674	if eAttachmentType == vboxcon.NetworkAttachmentType_NAT:
1675	oNic.attachToNAT();
1676	elif eAttachmentType == vboxcon.NetworkAttachmentType_Bridged:
1677	oNic.attachToBridgedInterface();
1678	elif eAttachmentType == vboxcon.NetworkAttachmentType_Internal:
1679	oNic.attachToInternalNetwork();
1680	elif eAttachmentType == vboxcon.NetworkAttachmentType_HostOnly:
1681	oNic.attachToHostOnlyInterface();
1682	else:
1683	raise base.GenError("eAttachmentType=%s is invalid" % (eAttachmentType));
1684	except:
1685	reporter.errorXcpt('failed to set the attachment type on slot %s to %s for VM "%s"' \
1686	% (iNic, eAttachmentType, self.sName));
1687	return False;
1688	else:
1689	try:
1690	eAttachmentType = oNic.attachmentType;
1691	except:
1692	reporter.errorXcpt('failed to get the attachment type on slot %s for VM "%s"' % (iNic, self.sName));
1693	return False;
1694	finally:
1695	self.oTstDrv.processPendingEvents();
1696
1697	if sName is not None:
1698	# Resolve the special 'default' name.
1699	if sName == 'default':
1700	sName = self.getDefaultNicName(eAttachmentType);
1701
1702	# The name translate to different attributes depending on the
1703	# attachment type.
1704	try:
1705	if eAttachmentType == vboxcon.NetworkAttachmentType_Bridged:
1706	## @todo check this out on windows, may have to do a
1707	# translation of the name there or smth IIRC.
1708	try:
1709	if self.fpApiVer >= 4.1:
1710	oNic.bridgedInterface = sName;
1711	else:
1712	oNic.hostInterface = sName;
1713	except:
1714	reporter.errorXcpt('failed to set the hostInterface property on slot %s to "%s" for VM "%s"'
1715	% (iNic, sName, self.sName,));
1716	return False;
1717	elif eAttachmentType == vboxcon.NetworkAttachmentType_HostOnly:
1718	try:
1719	if self.fpApiVer >= 4.1:
1720	oNic.hostOnlyInterface = sName;
1721	else:
1722	oNic.hostInterface = sName;
1723	except:
1724	reporter.errorXcpt('failed to set the internalNetwork property on slot %s to "%s" for VM "%s"'
1725	% (iNic, sName, self.sName,));
1726	return False;
1727	elif self.fpApiVer >= 7.0 and eAttachmentType == vboxcon.NetworkAttachmentType_HostOnlyNetwork:
1728	try:
1729	oNic.hostOnlyNetwork = sName;
1730	except:
1731	reporter.errorXcpt('failed to set the hostOnlyNetwork property on slot %s to "%s" for VM "%s"'
1732	% (iNic, sName, self.sName,));
1733	return False;
1734	elif eAttachmentType == vboxcon.NetworkAttachmentType_Internal:
1735	try:
1736	oNic.internalNetwork = sName;
1737	except:
1738	reporter.errorXcpt('failed to set the internalNetwork property on slot %s to "%s" for VM "%s"'
1739	% (iNic, sName, self.sName,));
1740	return False;
1741	elif eAttachmentType == vboxcon.NetworkAttachmentType_NAT:
1742	try:
1743	oNic.NATNetwork = sName;
1744	except:
1745	reporter.errorXcpt('failed to set the NATNetwork property on slot %s to "%s" for VM "%s"'
1746	% (iNic, sName, self.sName,));
1747	return False;
1748	finally:
1749	self.oTstDrv.processPendingEvents();
1750
1751	if not self.setupNatForwardingForTxs(iNic):
1752	return False;
1753	reporter.log('set NIC attachment type on slot %s to %s for VM "%s"' % (iNic, eAttachmentType, self.sName));
1754	return True;
1755
1756	def setNicLocalhostReachable(self, fReachable, iNic = 0):
1757	"""
1758	Sets whether the specified NIC can reach the host or not.
1759	Only affects (enabled) NICs configured to NAT at the moment.
1760
1761	Returns True on success and False on failure. Error information is logged.
1762	"""
1763	try:
1764	oNic = self.o.machine.getNetworkAdapter(iNic);
1765	except:
1766	return reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName,));
1767
1768	try:
1769	if not oNic.enabled: # NIC not enabled? Nothing to do here.
1770	return True;
1771	except:
1772	return reporter.errorXcpt('NIC enabled status (%s) failed for "%s"' % (iNic, self.sName,));
1773
1774	reporter.log('Setting "LocalhostReachable" for network adapter in slot %d to %s' % (iNic, fReachable));
1775
1776	try:
1777	oNatEngine = oNic.NATEngine;
1778	except:
1779	return reporter.errorXcpt('Getting NIC NAT engine (%s) failed for "%s"' % (iNic, self.sName,));
1780
1781	try:
1782	if hasattr(oNatEngine, "localhostReachable"):
1783	oNatEngine.localhostReachable = fReachable;
1784	else:
1785	oNatEngine.LocalhostReachable = fReachable;
1786	except:
1787	return reporter.errorXcpt('LocalhostReachable (%s) failed for "%s"' % (iNic, self.sName,));
1788
1789	return True;
1790
1791	def setNicMacAddress(self, sMacAddr, iNic = 0):
1792	"""
1793	Sets the MAC address of the specified NIC.
1794
1795	The sMacAddr parameter is a string supplying the tail end of the MAC
1796	address, missing quads are supplied from a constant byte (2), the IPv4
1797	address of the host, and the NIC number.
1798
1799	Returns True on success and False on failure. Error information is logged.
1800	"""
1801
1802	# Resolve missing MAC address prefix by feeding in the host IP address bytes.
1803	cchMacAddr = len(sMacAddr);
1804	if 0 < cchMacAddr < 12:
1805	sHostIP = netutils.getPrimaryHostIp();
1806	abHostIP = socket.inet_aton(sHostIP);
1807	if sys.version_info[0] < 3:
1808	abHostIP = (ord(abHostIP[0]), ord(abHostIP[1]), ord(abHostIP[2]), ord(abHostIP[3]));
1809
1810	if abHostIP[0] == 127 \
1811	or (abHostIP[0] == 169 and abHostIP[1] == 254) \
1812	or (abHostIP[0] == 192 and abHostIP[1] == 168 and abHostIP[2] == 56):
1813	return reporter.error('host IP for "%s" is %s, most likely not unique.' % (netutils.getHostnameFqdn(), sHostIP,));
1814
1815	sDefaultMac = '%02X%02X%02X%02X%02X%02X' % (0x02, abHostIP[0], abHostIP[1], abHostIP[2], abHostIP[3], iNic);
1816	sMacAddr = sDefaultMac[0:(12 - cchMacAddr)] + sMacAddr;
1817
1818	# Get the NIC object and try set it address.
1819	try:
1820	oNic = self.o.machine.getNetworkAdapter(iNic);
1821	except:
1822	return reporter.errorXcpt('getNetworkAdapter(%s) failed for "%s"' % (iNic, self.sName,));
1823
1824	try:
1825	oNic.MACAddress = sMacAddr;
1826	except:
1827	return reporter.errorXcpt('failed to set the MAC address on slot %s to "%s" for VM "%s"'
1828	% (iNic, sMacAddr, self.sName));
1829
1830	reporter.log('set MAC address on slot %s to %s for VM "%s"' % (iNic, sMacAddr, self.sName,));
1831	return True;
1832
1833	def setRamSize(self, cMB):
1834	"""
1835	Set the RAM size of the VM.
1836	Returns True on success and False on failure. Error information is logged.
1837	"""
1838	fRc = True;
1839	try:
1840	self.o.machine.memorySize = cMB;
1841	except:
1842	reporter.errorXcpt('failed to set the RAM size of "%s" to %s' % (self.sName, cMB));
1843	fRc = False;
1844	else:
1845	reporter.log('set the RAM size of "%s" to %s' % (self.sName, cMB));
1846	self.oTstDrv.processPendingEvents();
1847	return fRc;
1848
1849	def setLargePagesX86(self, fUseLargePages):
1850	"""
1851	Configures whether the VM should use large pages or not. x86 only.
1852	Returns True on success and False on failure. Error information is logged.
1853
1854	Ignored on non-x86 platform architectures.
1855	"""
1856	if not self.isPlatformX86(): return True;
1857	fRc = True;
1858	try:
1859	if self.fpApiVer >= 7.1:
1860	self.o.machine.platform.x86.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_LargePages, fUseLargePages);
1861	else:
1862	self.o.machine.setHWVirtExProperty(vboxcon.HWVirtExPropertyType_LargePages, fUseLargePages);
1863	except:
1864	reporter.errorXcpt('failed to set large pages of "%s" to %s' % (self.sName, fUseLargePages));
1865	fRc = False;
1866	else:
1867	reporter.log('set the large pages of "%s" to %s' % (self.sName, fUseLargePages));
1868	self.oTstDrv.processPendingEvents();
1869	return fRc;
1870
1871	def setVRamSize(self, cMB):
1872	"""
1873	Set the RAM size of the VM.
1874	Returns True on success and False on failure. Error information is logged.
1875	"""
1876	fRc = True;
1877	try:
1878	if self.fpApiVer >= 6.1 and hasattr(self.o.machine, 'graphicsAdapter'):
1879	self.o.machine.graphicsAdapter.VRAMSize = cMB;
1880	else:
1881	self.o.machine.VRAMSize = cMB;
1882	except:
1883	reporter.errorXcpt('failed to set the VRAM size of "%s" to %s' % (self.sName, cMB));
1884	fRc = False;
1885	else:
1886	reporter.log('set the VRAM size of "%s" to %s' % (self.sName, cMB));
1887	self.oTstDrv.processPendingEvents();
1888	return fRc;
1889
1890	def setVideoControllerType(self, eControllerType):
1891	"""
1892	Set the video controller type of the VM.
1893	Returns True on success and False on failure. Error information is logged.
1894	"""
1895	fRc = True;
1896	try:
1897	if self.fpApiVer >= 6.1 and hasattr(self.o.machine, 'graphicsAdapter'):
1898	self.o.machine.graphicsAdapter.graphicsControllerType = eControllerType;
1899	else:
1900	self.o.machine.graphicsControllerType = eControllerType;
1901	except:
1902	reporter.errorXcpt('failed to set the video controller type of "%s" to %s' % (self.sName, eControllerType));
1903	fRc = False;
1904	else:
1905	reporter.log('set the video controller type of "%s" to %s' % (self.sName, eControllerType));
1906	self.oTstDrv.processPendingEvents();
1907	return fRc;
1908
1909	def setAccelerate3DEnabled(self, fEnabled):
1910	"""
1911	Set the video controller type of the VM.
1912	Returns True on success and False on failure. Error information is logged.
1913	"""
1914	fRc = True;
1915	try:
1916	if self.fpApiVer >= 6.1 and hasattr(self.o.machine, 'graphicsAdapter'):
1917	self.o.machine.graphicsAdapter.accelerate3DEnabled = fEnabled;
1918	else:
1919	self.o.machine.accelerate3DEnabled = fEnabled;
1920	except:
1921	reporter.errorXcpt('failed to set the accelerate3DEnabled of "%s" to %s' % (self.sName, fEnabled));
1922	fRc = False;
1923	else:
1924	reporter.log('set the accelerate3DEnabled of "%s" to %s' % (self.sName, fEnabled));
1925	self.oTstDrv.processPendingEvents();
1926	return fRc;
1927
1928	def setCpuCount(self, cCpus):
1929	"""
1930	Set the number of CPUs.
1931	Returns True on success and False on failure. Error information is logged.
1932	"""
1933	fRc = True;
1934	try:
1935	self.o.machine.CPUCount = cCpus;
1936	except:
1937	reporter.errorXcpt('failed to set the CPU count of "%s" to %s' % (self.sName, cCpus));
1938	fRc = False;
1939	else:
1940	reporter.log('set the CPU count of "%s" to %s' % (self.sName, cCpus));
1941	self.oTstDrv.processPendingEvents();
1942	return fRc;
1943
1944	def getCpuCount(self):
1945	"""
1946	Returns the number of CPUs.
1947	Returns the number of CPUs on success and 0 on failure. Error information is logged.
1948	"""
1949	cCpus = 0;
1950	try:
1951	cCpus = self.o.machine.CPUCount;
1952	except:
1953	reporter.errorXcpt('failed to get the CPU count of "%s"' % (self.sName,));
1954
1955	self.oTstDrv.processPendingEvents();
1956	return cCpus;
1957
1958	def ensureControllerAttached(self, sController):
1959	"""
1960	Makes sure the specified controller is attached to the VM, attaching it
1961	if necessary.
1962	"""
1963	try:
1964	try:
1965	self.o.machine.getStorageControllerByName(sController);
1966	except:
1967	(eBus, eType) = _ControllerNameToBusAndType(sController);
1968	try:
1969	oCtl = self.o.machine.addStorageController(sController, eBus);
1970	except:
1971	reporter.errorXcpt('addStorageController("%s",%s) failed on "%s"' % (sController, eBus, self.sName) );
1972	return False;
1973	try:
1974	oCtl.controllerType = eType;
1975	reporter.log('added storage controller "%s" (bus %s, type %s) to %s'
1976	% (sController, eBus, eType, self.sName));
1977	except:
1978	reporter.errorXcpt('controllerType = %s on ("%s" / %s) failed on "%s"'
1979	% (eType, sController, eBus, self.sName) );
1980	return False;
1981	finally:
1982	self.oTstDrv.processPendingEvents();
1983	return True;
1984
1985	def setStorageControllerPortCount(self, sController, iPortCount):
1986	"""
1987	Set maximum ports count for storage controller
1988	"""
1989	try:
1990	oCtl = self.o.machine.getStorageControllerByName(sController)
1991	oCtl.portCount = iPortCount
1992	self.oTstDrv.processPendingEvents()
1993	reporter.log('set controller "%s" port count to value %d' % (sController, iPortCount))
1994	return True
1995	except:
1996	reporter.log('unable to set storage controller "%s" ports count to %d' % (sController, iPortCount))
1997
1998	return False
1999
2000	def setStorageControllerHostIoCache(self, sController, fUseHostIoCache):
2001	"""
2002	Set maximum ports count for storage controller
2003	"""
2004	try:
2005	oCtl = self.o.machine.getStorageControllerByName(sController);
2006	oCtl.useHostIOCache = fUseHostIoCache;
2007	self.oTstDrv.processPendingEvents();
2008	reporter.log('set controller "%s" host I/O cache setting to %r' % (sController, fUseHostIoCache));
2009	return True;
2010	except:
2011	reporter.log('unable to set storage controller "%s" host I/O cache setting to %r' % (sController, fUseHostIoCache));
2012
2013	return False;
2014
2015	def setBootOrder(self, iPosition, eType):
2016	"""
2017	Set guest boot order type
2018	@param iPosition boot order position
2019	@param eType device type (vboxcon.DeviceType_HardDisk,
2020	vboxcon.DeviceType_DVD, vboxcon.DeviceType_Floppy)
2021	"""
2022	try:
2023	self.o.machine.setBootOrder(iPosition, eType)
2024	except:
2025	return reporter.errorXcpt('Unable to set boot order.')
2026
2027	reporter.log('Set boot order [%d] for device %s' % (iPosition, str(eType)))
2028	self.oTstDrv.processPendingEvents();
2029
2030	return True
2031
2032	def setStorageControllerType(self, eType, sController = "IDE Controller"):
2033	"""
2034	Similar to ensureControllerAttached, except it will change the type.
2035	"""
2036	try:
2037	oCtl = self.o.machine.getStorageControllerByName(sController);
2038	except:
2039	(eBus, _) = _ControllerNameToBusAndType(sController);
2040	try:
2041	oCtl = self.o.machine.addStorageController(sController, eBus);
2042	reporter.log('added storage controller "%s" (bus %s) to %s' % (sController, eBus, self.sName));
2043	except:
2044	reporter.errorXcpt('addStorageController("%s",%s) failed on "%s"' % (sController, eBus, self.sName) );
2045	return False;
2046	try:
2047	oCtl.controllerType = eType;
2048	except:
2049	reporter.errorXcpt('failed to set controller type of "%s" on "%s" to %s' % (sController, self.sName, eType) );
2050	return False;
2051	reporter.log('set controller type of "%s" on "%s" to %s' % (sController, self.sName, eType) );
2052	self.oTstDrv.processPendingEvents();
2053	return True;
2054
2055	def attachDvd(self, sImage = None, sController = "IDE Controller", iPort = 1, iDevice = 0):
2056	"""
2057	Attaches a DVD drive to a VM, optionally with an ISO inserted.
2058	Returns True on success and False on failure. Error information is logged.
2059	"""
2060	# Input validation.
2061	if sImage is not None and not self.oTstDrv.isResourceFile(sImage)\
2062	and not os.path.isabs(sImage): ## fixme - testsuite unzip ++
2063	reporter.fatal('"%s" is not in the resource set' % (sImage));
2064	return None;
2065
2066	if not self.ensureControllerAttached(sController):
2067	return False;
2068
2069	# Find/register the image if specified.
2070	oImage = None;
2071	sImageUuid = "";
2072	if sImage is not None:
2073	sFullName = self.oTstDrv.getFullResourceName(sImage)
2074	try:
2075	oImage = self.oVBox.findDVDImage(sFullName);
2076	except:
2077	try:
2078	if self.fpApiVer >= 4.1:
2079	oImage = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_DVD, vboxcon.AccessMode_ReadOnly, False);
2080	elif self.fpApiVer >= 4.0:
2081	oImage = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_DVD, vboxcon.AccessMode_ReadOnly);
2082	else:
2083	oImage = self.oVBox.openDVDImage(sFullName, "");
2084	except vbox.ComException as oXcpt:
2085	if oXcpt.errno != -1:
2086	reporter.errorXcpt('failed to open DVD image "%s" xxx' % (sFullName));
2087	else:
2088	reporter.errorXcpt('failed to open DVD image "%s" yyy' % (sFullName));
2089	return False;
2090	except:
2091	reporter.errorXcpt('failed to open DVD image "%s"' % (sFullName));
2092	return False;
2093	try:
2094	sImageUuid = oImage.id;
2095	except:
2096	reporter.errorXcpt('failed to get the UUID of "%s"' % (sFullName));
2097	return False;
2098
2099	# Attach the DVD.
2100	fRc = True;
2101	try:
2102	if self.fpApiVer >= 4.0:
2103	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_DVD, oImage);
2104	else:
2105	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_DVD, sImageUuid);
2106	except:
2107	reporter.errorXcpt('attachDevice("%s",%s,%s,HardDisk,"%s") failed on "%s"' \
2108	% (sController, iPort, iDevice, sImageUuid, self.sName) );
2109	fRc = False;
2110	else:
2111	reporter.log('attached DVD to %s, image="%s"' % (self.sName, sImage));
2112	self.oTstDrv.processPendingEvents();
2113	return fRc;
2114
2115	def attachHd(self, sHd, sController = "IDE Controller", iPort = 0, iDevice = 0, fImmutable = True, fForceResource = True):
2116	"""
2117	Attaches a HD to a VM.
2118	Returns True on success and False on failure. Error information is logged.
2119	"""
2120	# Input validation.
2121	if fForceResource and not self.oTstDrv.isResourceFile(sHd):
2122	reporter.fatal('"%s" is not in the resource set' % (sHd,));
2123	return None;
2124
2125	if not self.ensureControllerAttached(sController):
2126	return False;
2127
2128	# Find the HD, registering it if necessary (as immutable).
2129	if fForceResource:
2130	sFullName = self.oTstDrv.getFullResourceName(sHd);
2131	else:
2132	sFullName = sHd;
2133	try:
2134	oHd = self.oVBox.findHardDisk(sFullName);
2135	except:
2136	try:
2137	if self.fpApiVer >= 4.1:
2138	oHd = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_HardDisk, vboxcon.AccessMode_ReadOnly, False);
2139	elif self.fpApiVer >= 4.0:
2140	oHd = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_HardDisk, vboxcon.AccessMode_ReadOnly);
2141	else:
2142	oHd = self.oVBox.openHardDisk(sFullName, vboxcon.AccessMode_ReadOnly, False, "", False, "");
2143	except:
2144	reporter.errorXcpt('failed to open hd "%s"' % (sFullName));
2145	return False;
2146	try:
2147	if fImmutable:
2148	oHd.type = vboxcon.MediumType_Immutable;
2149	else:
2150	oHd.type = vboxcon.MediumType_Normal;
2151	except:
2152	if fImmutable:
2153	reporter.errorXcpt('failed to set hd "%s" immutable' % (sHd));
2154	else:
2155	reporter.errorXcpt('failed to set hd "%s" normal' % (sHd));
2156	return False;
2157
2158	# Attach it.
2159	fRc = True;
2160	try:
2161	if self.fpApiVer >= 4.0:
2162	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_HardDisk, oHd);
2163	else:
2164	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_HardDisk, oHd.id);
2165	except:
2166	reporter.errorXcpt('attachDevice("%s",%s,%s,HardDisk,"%s") failed on "%s"' \
2167	% (sController, iPort, iDevice, oHd.id, self.sName) );
2168	fRc = False;
2169	else:
2170	reporter.log('attached "%s" to %s' % (sHd, self.sName));
2171	self.oTstDrv.processPendingEvents();
2172	return fRc;
2173
2174	def createBaseHd(self, sHd, sFmt = "VDI", cb = 1010241024*1024, cMsTimeout = 60000, tMediumVariant = None):
2175	"""
2176	Creates a base HD.
2177	Returns Medium object on success and None on failure. Error information is logged.
2178	"""
2179	if tMediumVariant is None:
2180	tMediumVariant = (vboxcon.MediumVariant_Standard, );
2181
2182	try:
2183	if self.fpApiVer >= 5.0:
2184	oHd = self.oVBox.createMedium(sFmt, sHd, vboxcon.AccessMode_ReadWrite, vboxcon.DeviceType_HardDisk);
2185	else:
2186	oHd = self.oVBox.createHardDisk(sFmt, sHd);
2187	oProgressXpcom = oHd.createBaseStorage(cb, tMediumVariant);
2188	oProgress = ProgressWrapper(oProgressXpcom, self.oVBoxMgr, self.oTstDrv, 'create base disk %s' % (sHd));
2189	oProgress.wait(cMsTimeout);
2190	oProgress.logResult();
2191	except:
2192	reporter.errorXcpt('failed to create base hd "%s"' % (sHd));
2193	oHd = None
2194
2195	return oHd;
2196
2197	def createDiffHd(self, oParentHd, sHd, sFmt = "VDI"):
2198	"""
2199	Creates a differencing HD.
2200	Returns Medium object on success and None on failure. Error information is logged.
2201	"""
2202	# Detect the proper format if requested
2203	if sFmt is None:
2204	try:
2205	oHdFmt = oParentHd.mediumFormat;
2206	lstCaps = self.oVBoxMgr.getArray(oHdFmt, 'capabilities');
2207	if vboxcon.MediumFormatCapabilities_Differencing in lstCaps:
2208	sFmt = oHdFmt.id;
2209	else:
2210	sFmt = 'VDI';
2211	except:
2212	reporter.errorXcpt('failed to get preferred diff format for "%s"' % (sHd));
2213	return None;
2214	try:
2215	if self.fpApiVer >= 5.0:
2216	oHd = self.oVBox.createMedium(sFmt, sHd, vboxcon.AccessMode_ReadWrite, vboxcon.DeviceType_HardDisk);
2217	else:
2218	oHd = self.oVBox.createHardDisk(sFmt, sHd);
2219	oProgressXpcom = oParentHd.createDiffStorage(oHd, (vboxcon.MediumVariant_Standard, ))
2220	oProgress = ProgressWrapper(oProgressXpcom, self.oVBoxMgr, self.oTstDrv, 'create diff disk %s' % (sHd));
2221	oProgress.wait();
2222	oProgress.logResult();
2223	except:
2224	reporter.errorXcpt('failed to create diff hd "%s"' % (sHd));
2225	oHd = None
2226
2227	return oHd;
2228
2229	def createAndAttachHd(self, sHd, sFmt = "VDI", sController = "IDE Controller", cb = 1010241024*1024, # pylint: disable=too-many-arguments
2230	iPort = 0, iDevice = 0, fImmutable = True, cMsTimeout = 60000, tMediumVariant = None):
2231	"""
2232	Creates and attaches a HD to a VM.
2233	Returns True on success and False on failure. Error information is logged.
2234	"""
2235	if not self.ensureControllerAttached(sController):
2236	return False;
2237
2238	oHd = self.createBaseHd(sHd, sFmt, cb, cMsTimeout, tMediumVariant);
2239	if oHd is None:
2240	return False;
2241
2242	fRc = True;
2243	try:
2244	if fImmutable:
2245	oHd.type = vboxcon.MediumType_Immutable;
2246	else:
2247	oHd.type = vboxcon.MediumType_Normal;
2248	except:
2249	if fImmutable:
2250	reporter.errorXcpt('failed to set hd "%s" immutable' % (sHd));
2251	else:
2252	reporter.errorXcpt('failed to set hd "%s" normal' % (sHd));
2253	fRc = False;
2254
2255	# Attach it.
2256	if fRc is True:
2257	try:
2258	if self.fpApiVer >= 4.0:
2259	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_HardDisk, oHd);
2260	else:
2261	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_HardDisk, oHd.id);
2262	except:
2263	reporter.errorXcpt('attachDevice("%s",%s,%s,HardDisk,"%s") failed on "%s"' \
2264	% (sController, iPort, iDevice, oHd.id, self.sName) );
2265	fRc = False;
2266	else:
2267	reporter.log('attached "%s" to %s' % (sHd, self.sName));
2268
2269	# Delete disk in case of an error
2270	if fRc is False:
2271	try:
2272	oProgressCom = oHd.deleteStorage();
2273	except:
2274	reporter.errorXcpt('deleteStorage() for disk %s failed' % (sHd,));
2275	else:
2276	oProgress = ProgressWrapper(oProgressCom, self.oVBoxMgr, self.oTstDrv, 'delete disk %s' % (sHd));
2277	oProgress.wait();
2278	oProgress.logResult();
2279
2280	self.oTstDrv.processPendingEvents();
2281	return fRc;
2282
2283	def detachHd(self, sController = "IDE Controller", iPort = 0, iDevice = 0):
2284	"""
2285	Detaches a HD, if attached, and returns a reference to it (IMedium).
2286
2287	In order to delete the detached medium, the caller must first save
2288	the changes made in this session.
2289
2290	Returns (fRc, oHd), where oHd is None unless fRc is True, and fRc is
2291	your standard success indicator. Error information is logged.
2292	"""
2293
2294	# What's attached?
2295	try:
2296	oHd = self.o.machine.getMedium(sController, iPort, iDevice);
2297	except:
2298	if self.oVBoxMgr.xcptIsOurXcptKind() \
2299	and self.oVBoxMgr.xcptIsEqual(None, self.oVBoxMgr.constants.VBOX_E_OBJECT_NOT_FOUND):
2300	reporter.log('No HD attached (to %s %s:%s)' % (sController, iPort, iDevice));
2301	return (True, None);
2302	return (reporter.errorXcpt('Error getting media at port %s, device %s, on %s.'
2303	% (iPort, iDevice, sController)), None);
2304	# Detach it.
2305	try:
2306	self.o.machine.detachDevice(sController, iPort, iDevice);
2307	except:
2308	return (reporter.errorXcpt('detachDevice("%s",%s,%s) failed on "%s"' \
2309	% (sController, iPort, iDevice, self.sName) ), None);
2310	reporter.log('detached HD ("%s",%s,%s) from %s' % (sController, iPort, iDevice, self.sName));
2311	return (True, oHd);
2312
2313	def attachFloppy(self, sFloppy, sController = "Floppy Controller", iPort = 0, iDevice = 0):
2314	"""
2315	Attaches a floppy image to a VM.
2316	Returns True on success and False on failure. Error information is logged.
2317	"""
2318	# Input validation.
2319	## @todo Fix this wrt to bootsector-xxx.img from the validationkit.zip.
2320	##if not self.oTstDrv.isResourceFile(sFloppy):
2321	## reporter.fatal('"%s" is not in the resource set' % (sFloppy));
2322	## return None;
2323
2324	if not self.ensureControllerAttached(sController):
2325	return False;
2326
2327	# Find the floppy image, registering it if necessary (as immutable).
2328	sFullName = self.oTstDrv.getFullResourceName(sFloppy);
2329	try:
2330	oFloppy = self.oVBox.findFloppyImage(sFullName);
2331	except:
2332	try:
2333	if self.fpApiVer >= 4.1:
2334	oFloppy = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_Floppy, vboxcon.AccessMode_ReadOnly, False);
2335	elif self.fpApiVer >= 4.0:
2336	oFloppy = self.oVBox.openMedium(sFullName, vboxcon.DeviceType_Floppy, vboxcon.AccessMode_ReadOnly);
2337	else:
2338	oFloppy = self.oVBox.openFloppyImage(sFullName, "");
2339	except:
2340	reporter.errorXcpt('failed to open floppy "%s"' % (sFullName));
2341	return False;
2342	## @todo the following works but causes trouble below (asserts in main).
2343	#try:
2344	# oFloppy.type = vboxcon.MediumType_Immutable;
2345	#except:
2346	# reporter.errorXcpt('failed to make floppy "%s" immutable' % (sFullName));
2347	# return False;
2348
2349	# Attach it.
2350	fRc = True;
2351	try:
2352	if self.fpApiVer >= 4.0:
2353	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_Floppy, oFloppy);
2354	else:
2355	self.o.machine.attachDevice(sController, iPort, iDevice, vboxcon.DeviceType_Floppy, oFloppy.id);
2356	except:
2357	reporter.errorXcpt('attachDevice("%s",%s,%s,Floppy,"%s") failed on "%s"' \
2358	% (sController, iPort, iDevice, oFloppy.id, self.sName) );
2359	fRc = False;
2360	else:
2361	reporter.log('attached "%s" to %s' % (sFloppy, self.sName));
2362	self.oTstDrv.processPendingEvents();
2363	return fRc;
2364
2365	def setupNic(self, sType, sXXX):
2366	"""
2367	Sets up a NIC to a VM.
2368	Returns True on success and False on failure. Error information is logged.
2369	"""
2370	if sType == "PCNet": enmType = vboxcon.NetworkAdapterType_Am79C973;
2371	elif sType == "PCNetOld": enmType = vboxcon.NetworkAdapterType_Am79C970A;
2372	elif sType == "E1000": enmType = vboxcon.NetworkAdapterType_I82545EM; # MT Server
2373	elif sType == "E1000Desk": enmType = vboxcon.NetworkAdapterType_I82540EM; # MT Desktop
2374	elif sType == "E1000Srv2": enmType = vboxcon.NetworkAdapterType_I82543GC; # T Server
2375	elif sType == "Virtio": enmType = vboxcon.NetworkAdapterType_Virtio;
2376	else:
2377	reporter.error('Invalid NIC type: "%s" (sXXX=%s)' % (sType, sXXX));
2378	return False;
2379	## @todo Implement me!
2380	if enmType is not None: pass
2381	return True;
2382
2383	def setupAudio(self, eAudioControllerType, fEnable = True, fEnableIn = False, fEnableOut = True, eAudioDriverType = None):
2384	"""
2385	Sets up audio.
2386
2387	:param eAudioControllerType: The audio controller type (vboxcon.AudioControllerType_XXX).
2388	:param fEnable: Whether to enable or disable the audio controller (default enable).
2389	:param fEnableIn: Whether to enable or disable audio input (default disable).
2390	:param fEnableOut: Whether to enable or disable audio output (default enable).
2391	:param eAudioDriverType: The audio driver type (vboxcon.AudioDriverType_XXX), picks something suitable
2392	if None is passed (default).
2393	"""
2394	try:
2395	if self.fpApiVer >= 7.0:
2396	oAdapter = self.o.machine.audioSettings.adapter;
2397	else:
2398	oAdapter = self.o.machine.audioAdapter;
2399	except: return reporter.errorXcpt('Failed to get the audio adapter.');
2400
2401	try: oAdapter.audioController = eAudioControllerType;
2402	except: return reporter.errorXcpt('Failed to set the audio controller to %s.' % (eAudioControllerType,));
2403
2404	if eAudioDriverType is None:
2405	if self.fpApiVer >= 7.1:
2406	eAudioDriverType = vboxcon.AudioDriverType_Default;
2407	else:
2408	sHost = utils.getHostOs()
2409	if sHost == 'darwin': eAudioDriverType = vboxcon.AudioDriverType_CoreAudio;
2410	elif sHost == 'win': eAudioDriverType = vboxcon.AudioDriverType_DirectSound;
2411	elif sHost == 'linux': eAudioDriverType = vboxcon.AudioDriverType_Pulse;
2412	elif sHost == 'solaris': eAudioDriverType = vboxcon.AudioDriverType_OSS;
2413	else:
2414	reporter.error('PORTME: Do not know which audio driver to pick for: %s!' % (sHost,));
2415	eAudioDriverType = vboxcon.AudioDriverType_Null;
2416
2417	try: oAdapter.audioDriver = eAudioDriverType;
2418	except: return reporter.errorXcpt('Failed to set the audio driver to %s.' % (eAudioDriverType,))
2419
2420	try: oAdapter.enabled = fEnable;
2421	except: return reporter.errorXcpt('Failed to set the "enabled" property to %s.' % (fEnable,));
2422
2423	try: oAdapter.enabledIn = fEnableIn;
2424	except: return reporter.errorXcpt('Failed to set the "enabledIn" property to %s.' % (fEnable,));
2425
2426	try: oAdapter.enabledOut = fEnableOut;
2427	except: return reporter.errorXcpt('Failed to set the "enabledOut" property to %s.' % (fEnable,));
2428
2429	reporter.log('set audio controller type to %d, driver to %d, and enabled to %s (input is %s, output is %s)'
2430	% (eAudioControllerType, eAudioDriverType, fEnable, fEnableIn, fEnableOut,));
2431	self.oTstDrv.processPendingEvents();
2432	return True;
2433
2434	def setupPreferredConfig(self): # pylint: disable=too-many-locals
2435	"""
2436	Configures the VM according to the preferences of the guest type.
2437	"""
2438	try:
2439	sOsTypeId = self.o.machine.OSTypeId;
2440	except:
2441	reporter.errorXcpt('failed to obtain the OSTypeId for "%s"' % (self.sName));
2442	return False;
2443
2444	try:
2445	oOsType = self.oVBox.getGuestOSType(sOsTypeId);
2446	except:
2447	reporter.errorXcpt('getGuestOSType("%s") failed for "%s"' % (sOsTypeId, self.sName));
2448	return False;
2449
2450	# get the attributes.
2451	try:
2452	#sFamilyId = oOsType.familyId;
2453	#f64Bit = oOsType.is64Bit;
2454	fIoApic = oOsType.recommendedIOAPIC;
2455	fVirtEx = oOsType.recommendedVirtEx;
2456	cMBRam = oOsType.recommendedRAM;
2457	cMBVRam = oOsType.recommendedVRAM;
2458	#cMBHdd = oOsType.recommendedHDD;
2459	eNicType = oOsType.adapterType;
2460	if self.fpApiVer >= 3.2:
2461	if self.fpApiVer >= 4.2:
2462	fPae = oOsType.recommendedPAE;
2463	fUsbHid = oOsType.recommendedUSBHID;
2464	fHpet = oOsType.recommendedHPET;
2465	eStorCtlType = oOsType.recommendedHDStorageController;
2466	else:
2467	fPae = oOsType.recommendedPae;
2468	fUsbHid = oOsType.recommendedUsbHid;
2469	fHpet = oOsType.recommendedHpet;
2470	eStorCtlType = oOsType.recommendedHdStorageController;
2471	eFirmwareType = oOsType.recommendedFirmware;
2472	else:
2473	fPae = False;
2474	fUsbHid = False;
2475	fHpet = False;
2476	eFirmwareType = -1;
2477	eStorCtlType = vboxcon.StorageControllerType_PIIX4;
2478	if self.fpApiVer >= 4.0:
2479	eAudioCtlType = oOsType.recommendedAudioController;
2480	except:
2481	reporter.errorXcpt('exception reading IGuestOSType(%s) attribute' % (sOsTypeId));
2482	self.oTstDrv.processPendingEvents();
2483	return False;
2484	self.oTstDrv.processPendingEvents();
2485
2486	# Do the setting. Continue applying settings on error in case the
2487	# caller ignores the return code
2488	fRc = True;
2489	if not self.enableIoApic(fIoApic): fRc = False;
2490	if not self.enableVirtExX86(fVirtEx): fRc = False;
2491	if not self.enablePaeX86(fPae): fRc = False;
2492	if not self.setRamSize(cMBRam): fRc = False;
2493	if not self.setVRamSize(cMBVRam): fRc = False;
2494	if not self.setNicType(eNicType, 0): fRc = False;
2495	if self.fpApiVer >= 3.2:
2496	if not self.setFirmwareType(eFirmwareType): fRc = False;
2497	if not self.enableUsbHid(fUsbHid): fRc = False;
2498	if not self.enableHpetX86(fHpet): fRc = False;
2499	if eStorCtlType in (vboxcon.StorageControllerType_PIIX3,
2500	vboxcon.StorageControllerType_PIIX4,
2501	vboxcon.StorageControllerType_ICH6,):
2502	if not self.setStorageControllerType(eStorCtlType, "IDE Controller"):
2503	fRc = False;
2504	if self.fpApiVer >= 4.0:
2505	if not self.setupAudio(eAudioCtlType): fRc = False;
2506
2507	return fRc;
2508
2509	def addUsbDeviceFilter(self, sName, sVendorId = None, sProductId = None, sRevision = None, # pylint: disable=too-many-arguments
2510	sManufacturer = None, sProduct = None, sSerialNumber = None,
2511	sPort = None, sRemote = None):
2512	"""
2513	Creates a USB device filter and inserts it into the VM.
2514	Returns True on success.
2515	Returns False on failure (logged).
2516	"""
2517	fRc = True;
2518
2519	try:
2520	oUsbDevFilter = self.o.machine.USBDeviceFilters.createDeviceFilter(sName);
2521	oUsbDevFilter.active = True;
2522	if sVendorId is not None:
2523	oUsbDevFilter.vendorId = sVendorId;
2524	if sProductId is not None:
2525	oUsbDevFilter.productId = sProductId;
2526	if sRevision is not None:
2527	oUsbDevFilter.revision = sRevision;
2528	if sManufacturer is not None:
2529	oUsbDevFilter.manufacturer = sManufacturer;
2530	if sProduct is not None:
2531	oUsbDevFilter.product = sProduct;
2532	if sSerialNumber is not None:
2533	oUsbDevFilter.serialnumber = sSerialNumber;
2534	if sPort is not None:
2535	oUsbDevFilter.port = sPort;
2536	if sRemote is not None:
2537	oUsbDevFilter.remote = sRemote;
2538	try:
2539	self.o.machine.USBDeviceFilters.insertDeviceFilter(0, oUsbDevFilter);
2540	except:
2541	reporter.errorXcpt('insertDeviceFilter(%s) failed on "%s"' \
2542	% (0, self.sName) );
2543	fRc = False;
2544	else:
2545	reporter.log('inserted USB device filter "%s" to %s' % (sName, self.sName));
2546	except:
2547	reporter.errorXcpt('createDeviceFilter("%s") failed on "%s"' \
2548	% (sName, self.sName) );
2549	fRc = False;
2550	return fRc;
2551
2552	def getGuestPropertyValue(self, sName):
2553	"""
2554	Gets a guest property value.
2555	Returns the value on success, None on failure (logged).
2556	"""
2557	try:
2558	sValue = self.o.machine.getGuestPropertyValue(sName);
2559	except:
2560	reporter.errorXcpt('IMachine::getGuestPropertyValue("%s") failed' % (sName));
2561	return None;
2562	return sValue;
2563
2564	def setGuestPropertyValue(self, sName, sValue):
2565	"""
2566	Sets a guest property value.
2567	Returns the True on success, False on failure (logged).
2568	"""
2569	try:
2570	self.o.machine.setGuestPropertyValue(sName, sValue);
2571	except:
2572	reporter.errorXcpt('IMachine::setGuestPropertyValue("%s","%s") failed' % (sName, sValue));
2573	return False;
2574	return True;
2575
2576	def delGuestPropertyValue(self, sName):
2577	"""
2578	Deletes a guest property value.
2579	Returns the True on success, False on failure (logged).
2580	"""
2581	try:
2582	oMachine = self.o.machine;
2583	if self.fpApiVer >= 4.2:
2584	oMachine.deleteGuestProperty(sName);
2585	else:
2586	oMachine.setGuestPropertyValue(sName, '');
2587	except:
2588	reporter.errorXcpt('Unable to delete guest property "%s"' % (sName,));
2589	return False;
2590	return True;
2591
2592	def setExtraData(self, sKey, sValue):
2593	"""
2594	Sets extra data.
2595	Returns the True on success, False on failure (logged).
2596	"""
2597	try:
2598	self.o.machine.setExtraData(sKey, sValue);
2599	except:
2600	reporter.errorXcpt('IMachine::setExtraData("%s","%s") failed' % (sKey, sValue));
2601	return False;
2602	return True;
2603
2604	def getExtraData(self, sKey):
2605	"""
2606	Gets extra data.
2607	Returns value on success, None on failure.
2608	"""
2609	try:
2610	sValue = self.o.machine.getExtraData(sKey)
2611	except:
2612	reporter.errorXcpt('IMachine::getExtraData("%s") failed' % (sKey,))
2613	return None
2614	return sValue
2615
2616	def setupTeleporter(self, fEnabled=True, uPort = 6500, sAddress = '', sPassword = ''):
2617	"""
2618	Sets up the teleporter for the VM.
2619	Returns True on success, False on failure (logged).
2620	"""
2621	try:
2622	self.o.machine.teleporterAddress = sAddress;
2623	self.o.machine.teleporterPort = uPort;
2624	self.o.machine.teleporterPassword = sPassword;
2625	self.o.machine.teleporterEnabled = fEnabled;
2626	except:
2627	reporter.errorXcpt('setupTeleporter(%s, %s, %s, %s)' % (fEnabled, sPassword, uPort, sAddress));
2628	return False;
2629	return True;
2630
2631	def enableTeleporter(self, fEnable=True):
2632	"""
2633	Enables or disables the teleporter of the VM.
2634	Returns True on success, False on failure (logged).
2635	"""
2636	try:
2637	self.o.machine.teleporterEnabled = fEnable;
2638	except:
2639	reporter.errorXcpt('IMachine::teleporterEnabled=%s failed' % (fEnable));
2640	return False;
2641	return True;
2642
2643	def teleport(self, sHostname = 'localhost', uPort = 6500, sPassword = 'password', cMsMaxDowntime = 250):
2644	"""
2645	Wrapper around the IConsole::teleport() method.
2646	Returns a progress object on success, None on failure (logged).
2647	"""
2648	reporter.log2('"%s"::teleport(%s,%s,%s,%s)...' % (self.sName, sHostname, uPort, sPassword, cMsMaxDowntime));
2649	try:
2650	oProgress = self.o.console.teleport(sHostname, uPort, sPassword, cMsMaxDowntime)
2651	except:
2652	reporter.errorXcpt('IConsole::teleport(%s,%s,%s,%s) failed' % (sHostname, uPort, sPassword, cMsMaxDowntime));
2653	return None;
2654	return ProgressWrapper(oProgress, self.oVBoxMgr, self.oTstDrv, 'teleport %s' % (self.sName,));
2655
2656	def getOsType(self):
2657	"""
2658	Gets the IGuestOSType interface for the machine.
2659
2660	return IGuestOSType interface on success, None + errorXcpt on failure.
2661	No exceptions raised.
2662	"""
2663	try:
2664	sOsTypeId = self.o.machine.OSTypeId;
2665	except:
2666	reporter.errorXcpt('failed to obtain the OSTypeId for "%s"' % (self.sName));
2667	return None;
2668
2669	try:
2670	oOsType = self.oVBox.getGuestOSType(sOsTypeId);
2671	except:
2672	reporter.errorXcpt('getGuestOSType("%s") failed for "%s"' % (sOsTypeId, self.sName));
2673	return None;
2674
2675	return oOsType;
2676
2677	def setOsType(self, sNewTypeId):
2678	"""
2679	Changes the OS type.
2680
2681	returns True on success, False + errorXcpt on failure.
2682	No exceptions raised.
2683	"""
2684	try:
2685	self.o.machine.OSTypeId = sNewTypeId;
2686	except:
2687	reporter.errorXcpt('failed to set the OSTypeId for "%s" to "%s"' % (self.sName, sNewTypeId));
2688	return False;
2689	return True;
2690
2691
2692	def setParavirtProvider(self, iProvider):
2693	"""
2694	Sets a paravirtualisation provider.
2695	Returns the True on success, False on failure (logged).
2696	"""
2697	try:
2698	self.o.machine.paravirtProvider = iProvider
2699	except:
2700	reporter.errorXcpt('Unable to set paravirtualisation provider "%s"' % (iProvider,))
2701	return False;
2702	return True;
2703
2704
2705	def setupSerialToRawFile(self, iSerialPort, sRawFile):
2706	"""
2707	Enables the given serial port (zero based) and redirects it to sRawFile.
2708	Returns the True on success, False on failure (logged).
2709	"""
2710	try:
2711	oPort = self.o.machine.getSerialPort(iSerialPort);
2712	except:
2713	fRc = reporter.errorXcpt('failed to get serial port #%u' % (iSerialPort,));
2714	else:
2715	try:
2716	oPort.path = sRawFile;
2717	except:
2718	fRc = reporter.errorXcpt('failed to set the "path" property on serial port #%u to "%s"'
2719	% (iSerialPort, sRawFile));
2720	else:
2721	try:
2722	oPort.hostMode = vboxcon.PortMode_RawFile;
2723	except:
2724	fRc = reporter.errorXcpt('failed to set the "hostMode" property on serial port #%u to PortMode_RawFile'
2725	% (iSerialPort,));
2726	else:
2727	try:
2728	oPort.enabled = True;
2729	except:
2730	fRc = reporter.errorXcpt('failed to set the "enable" property on serial port #%u to True'
2731	% (iSerialPort,));
2732	else:
2733	reporter.log('set SerialPort[%s].enabled/hostMode/path=True/RawFile/%s' % (iSerialPort, sRawFile,));
2734	fRc = True;
2735	self.oTstDrv.processPendingEvents();
2736	return fRc;
2737
2738
2739	def enableSerialPort(self, iSerialPort):
2740	"""
2741	Enables the given serial port setting the initial port mode to disconnected.
2742	"""
2743	try:
2744	oPort = self.o.machine.getSerialPort(iSerialPort);
2745	except:
2746	fRc = reporter.errorXcpt('failed to get serial port #%u' % (iSerialPort,));
2747	else:
2748	try:
2749	oPort.hostMode = vboxcon.PortMode_Disconnected;
2750	except:
2751	fRc = reporter.errorXcpt('failed to set the "hostMode" property on serial port #%u to PortMode_Disconnected'
2752	% (iSerialPort,));
2753	else:
2754	try:
2755	oPort.enabled = True;
2756	except:
2757	fRc = reporter.errorXcpt('failed to set the "enable" property on serial port #%u to True'
2758	% (iSerialPort,));
2759	else:
2760	reporter.log('set SerialPort[%s].enabled/hostMode/=True/Disconnected' % (iSerialPort,));
2761	fRc = True;
2762	self.oTstDrv.processPendingEvents();
2763	return fRc;
2764
2765
2766	def changeSerialPortAttachment(self, iSerialPort, ePortMode, sPath, fServer):
2767	"""
2768	Changes the attachment of the given serial port to the attachment config given.
2769	"""
2770	try:
2771	oPort = self.o.machine.getSerialPort(iSerialPort);
2772	except:
2773	fRc = reporter.errorXcpt('failed to get serial port #%u' % (iSerialPort,));
2774	else:
2775	try:
2776	# Change port mode to disconnected first so changes get picked up by a potentially running VM.
2777	oPort.hostMode = vboxcon.PortMode_Disconnected;
2778	except:
2779	fRc = reporter.errorXcpt('failed to set the "hostMode" property on serial port #%u to PortMode_Disconnected'
2780	% (iSerialPort,));
2781	else:
2782	try:
2783	oPort.path = sPath;
2784	oPort.server = fServer;
2785	oPort.hostMode = ePortMode;
2786	except:
2787	fRc = reporter.errorXcpt('failed to configure the serial port');
2788	else:
2789	reporter.log('set SerialPort[%s].hostMode/path/server=%s/%s/%s'
2790	% (iSerialPort, ePortMode, sPath, fServer));
2791	fRc = True;
2792	self.oTstDrv.processPendingEvents();
2793	return fRc;
2794
2795	def setExecutionEngine(self, iVmExecEngine):
2796	"""
2797	Sets a VM execution engine.
2798	Returns the True on success, False on failure (logged).
2799	"""
2800	try:
2801	self.o.machine.VMExecutionEngine = iVmExecEngine;
2802	except:
2803	reporter.errorXcpt('Unable to set VM execution engine "%s"' % (iVmExecEngine,))
2804	return False;
2805	return True;
2806
2807	#
2808	# IConsole wrappers.
2809	#
2810
2811	def powerOff(self, fFudgeOnFailure = True):
2812	"""
2813	Powers off the VM.
2814
2815	Returns True on success.
2816	Returns False on IConsole::powerDown() failure.
2817	Returns None if the progress object returns failure.
2818	"""
2819	#
2820	# Deregister event handler before we power off the VM, otherwise we're
2821	# racing for VM process termination and cause misleading spurious
2822	# error messages in the event handling code, because the event objects
2823	# disappear.
2824	#
2825	# Note! Doing this before powerDown to try prevent numerous smoketest
2826	# timeouts on XPCOM hosts.
2827	#
2828	self.deregisterEventHandlerForTask();
2829
2830
2831	# Try power if off.
2832	try:
2833	oProgress = self.o.console.powerDown();
2834	except:
2835	reporter.logXcpt('IConsole::powerDown failed on %s' % (self.sName));
2836	if fFudgeOnFailure:
2837	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2838	self.waitForTask(1000); # fudge
2839	return False;
2840
2841	# Wait on power off operation to complete.
2842	rc = self.oTstDrv.waitOnProgress(oProgress);
2843	if rc < 0:
2844	self.close();
2845	if fFudgeOnFailure:
2846	vbox.reportError(oProgress, 'powerDown for "%s" failed' % (self.sName));
2847	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2848	return None;
2849
2850	# Wait for the VM to really power off or we'll fail to open a new session to it.
2851	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2852	return self.waitForTask(30 * 1000); # fudge
2853
2854	def saveState(self, fPause = True):
2855	"""
2856	Saves state of the VM.
2857
2858	Returns True on success.
2859	Returns False on IConsole::saveState() failure.
2860	Returns None if the progress object returns Failure.
2861	"""
2862
2863	if fPause is True \
2864	and self.oVM.state is vboxcon.MachineState_Running:
2865	self.o.console.pause();
2866	if self.oVM.state is not vboxcon.MachineState_Paused:
2867	reporter.error('pause for "%s" failed' % (self.sName));
2868	# Try saving state.
2869	try:
2870	if self.fpApiVer >= 5.0:
2871	oProgress = self.o.machine.saveState()
2872	else:
2873	oProgress = self.o.console.saveState()
2874	except:
2875	reporter.logXcpt('IMachine::saveState failed on %s' % (self.sName));
2876	return False;
2877
2878	# Wait for saving state operation to complete.
2879	rc = self.oTstDrv.waitOnProgress(oProgress);
2880	if rc < 0:
2881	self.close();
2882	return None;
2883
2884	# Wait for the VM to really terminate or we'll fail to open a new session to it.
2885	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2886	return self.waitForTask(30 * 1000); # fudge
2887
2888	def discardSavedState(self, fRemove = True):
2889	"""
2890	Discards saved state of the VM.
2891
2892	Returns True on success.
2893	Returns False on IConsole::discardSaveState() failure.
2894	"""
2895
2896	try:
2897	if self.fpApiVer >= 5.0:
2898	self.o.machine.discardSavedState(fRemove)
2899	else:
2900	self.o.console.discardSavedState(fRemove)
2901	except:
2902	reporter.logXcpt('IMachine::discardSavedState failed on %s' % (self.sName))
2903	return False
2904	return True
2905
2906	def restoreSnapshot(self, oSnapshot, fFudgeOnFailure = True):
2907	"""
2908	Restores the given snapshot.
2909
2910	Returns True on success.
2911	Returns False on IMachine::restoreSnapshot() failure.
2912	Returns None if the progress object returns failure.
2913	"""
2914	try:
2915	if self.fpApiVer >= 5.0:
2916	oProgress = self.o.machine.restoreSnapshot(oSnapshot);
2917	else:
2918	oProgress = self.o.console.restoreSnapshot(oSnapshot);
2919	except:
2920	reporter.logXcpt('IMachine::restoreSnapshot failed on %s' % (self.sName));
2921	if fFudgeOnFailure:
2922	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2923	self.waitForTask(1000); # fudge
2924	return False;
2925
2926	rc = self.oTstDrv.waitOnProgress(oProgress);
2927	if rc < 0:
2928	self.close();
2929	if fFudgeOnFailure:
2930	vbox.reportError(oProgress, 'restoreSnapshot for "%s" failed' % (self.sName));
2931	return None;
2932
2933	return self.waitForTask(30 * 1000);
2934
2935	def deleteSnapshot(self, oSnapshot, fFudgeOnFailure = True, cMsTimeout = 30 * 1000):
2936	"""
2937	Deletes the given snapshot merging the diff image into the base.
2938
2939	Returns True on success.
2940	Returns False on IMachine::deleteSnapshot() failure.
2941	"""
2942	try:
2943	if self.fpApiVer >= 5.0:
2944	oProgressCom = self.o.machine.deleteSnapshot(oSnapshot);
2945	else:
2946	oProgressCom = self.o.console.deleteSnapshot(oSnapshot);
2947	oProgress = ProgressWrapper(oProgressCom, self.oVBoxMgr, self.oTstDrv, 'Delete Snapshot %s' % (oSnapshot));
2948	oProgress.wait(cMsTimeout);
2949	oProgress.logResult();
2950	except:
2951	reporter.logXcpt('IMachine::deleteSnapshot failed on %s' % (self.sName));
2952	if fFudgeOnFailure:
2953	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2954	self.waitForTask(1000); # fudge
2955	return False;
2956
2957	return True;
2958
2959	def takeSnapshot(self, sName, sDescription = '', fPause = True, fFudgeOnFailure = True, cMsTimeout = 30 * 1000):
2960	"""
2961	Takes a snapshot with the given name
2962
2963	Returns True on success.
2964	Returns False on IMachine::takeSnapshot() or VM state change failure.
2965	"""
2966	try:
2967	if fPause is True \
2968	and self.oVM.state is vboxcon.MachineState_Running:
2969	self.o.console.pause();
2970	if self.fpApiVer >= 5.0:
2971	(oProgressCom, _) = self.o.machine.takeSnapshot(sName, sDescription, True);
2972	else:
2973	oProgressCom = self.o.console.takeSnapshot(sName, sDescription);
2974	oProgress = ProgressWrapper(oProgressCom, self.oVBoxMgr, self.oTstDrv, 'Take Snapshot %s' % (sName));
2975	oProgress.wait(cMsTimeout);
2976	oProgress.logResult();
2977	except:
2978	reporter.logXcpt('IMachine::takeSnapshot failed on %s' % (self.sName));
2979	if fFudgeOnFailure:
2980	self.oTstDrv.waitOnDirectSessionClose(self.oVM, 5000); # fudge
2981	self.waitForTask(1000); # fudge
2982	return False;
2983
2984	if fPause is True \
2985	and self.oVM.state is vboxcon.MachineState_Paused:
2986	self.o.console.resume();
2987
2988	return True;
2989
2990	def findSnapshot(self, sName):
2991	"""
2992	Returns the snapshot object with the given name
2993
2994	Returns snapshot object on success.
2995	Returns None if there is no snapshot with the given name.
2996	"""
2997	return self.oVM.findSnapshot(sName);
2998
2999	def takeScreenshot(self, sFilename, iScreenId=0):
3000	"""
3001	Take screenshot from the given display and save it to specified file.
3002
3003	Returns True on success
3004	Returns False on failure.
3005	"""
3006	try:
3007	if self.fpApiVer >= 5.0:
3008	iWidth, iHeight, _, _, _, _ = self.o.console.display.getScreenResolution(iScreenId)
3009	aPngData = self.o.console.display.takeScreenShotToArray(iScreenId, iWidth, iHeight,
3010	vboxcon.BitmapFormat_PNG)
3011	else:
3012	iWidth, iHeight, _, _, _ = self.o.console.display.getScreenResolution(iScreenId)
3013	aPngData = self.o.console.display.takeScreenShotPNGToArray(iScreenId, iWidth, iHeight)
3014	except:
3015	reporter.logXcpt("Unable to take screenshot")
3016	return False
3017
3018	with open(sFilename, 'wb') as oFile: # pylint: disable=unspecified-encoding
3019	oFile.write(aPngData)
3020
3021	return True
3022
3023	def attachUsbDevice(self, sUuid, sCaptureFilename = None):
3024	"""
3025	Attach given USB device UUID to the VM.
3026
3027	Returns True on success
3028	Returns False on failure.
3029	"""
3030	fRc = True;
3031	try:
3032	if sCaptureFilename is None:
3033	self.o.console.attachUSBDevice(sUuid, '');
3034	else:
3035	self.o.console.attachUSBDevice(sUuid, sCaptureFilename);
3036	except:
3037	reporter.logXcpt('Unable to attach USB device %s' % (sUuid,));
3038	fRc = False;
3039
3040	return fRc;
3041
3042	def detachUsbDevice(self, sUuid):
3043	"""
3044	Detach given USB device UUID from the VM.
3045
3046	Returns True on success
3047	Returns False on failure.
3048	"""
3049	fRc = True;
3050	try:
3051	_ = self.o.console.detachUSBDevice(sUuid);
3052	except:
3053	reporter.logXcpt('Unable to detach USB device %s' % (sUuid,));
3054	fRc = False;
3055
3056	return fRc;
3057
3058
3059	#
3060	# IMachineDebugger wrappers.
3061	#
3062
3063	def queryOsKernelLog(self):
3064	"""
3065	Tries to get the OS kernel log using the VM debugger interface.
3066
3067	Returns string containing the kernel log on success.
3068	Returns None on failure.
3069	"""
3070	sOsKernelLog = None;
3071	try:
3072	self.o.console.debugger.loadPlugIn('all');
3073	except:
3074	reporter.logXcpt('Unable to load debugger plugins');
3075	else:
3076	try:
3077	sOsDetected = self.o.console.debugger.detectOS();
3078	except:
3079	reporter.logXcpt('Failed to detect the guest OS');
3080	else:
3081	try:
3082	sOsKernelLog = self.o.console.debugger.queryOSKernelLog(0);
3083	except:
3084	reporter.logXcpt('Unable to get the guest OS (%s) kernel log' % (sOsDetected,));
3085	return sOsKernelLog;
3086
3087	def queryDbgInfo(self, sItem, sArg = '', sDefault = None):
3088	"""
3089	Simple wrapper around IMachineDebugger::info.
3090
3091	Returns string on success, sDefault on failure (logged).
3092	"""
3093	try:
3094	return self.o.console.debugger.info(sItem, sArg);
3095	except:
3096	reporter.logXcpt('Unable to query "%s" with arg "%s"' % (sItem, sArg,));
3097	return sDefault;
3098
3099	def queryDbgInfoVgaText(self, sArg = 'all'):
3100	"""
3101	Tries to get the 'info vgatext' output, provided we're in next mode.
3102
3103	Returns string containing text on success.
3104	Returns None on failure or not text mode.
3105	"""
3106	sVgaText = None;
3107	try:
3108	sVgaText = self.o.console.debugger.info('vgatext', sArg);
3109	if sVgaText.startswith('Not in text mode!'):
3110	sVgaText = None;
3111	except:
3112	reporter.logXcpt('Unable to query vgatext with arg "%s"' % (sArg,));
3113	return sVgaText;
3114
3115	def queryDbgGuestStack(self, iCpu = 0):
3116	"""
3117	Returns the guest stack for the given VCPU.
3118
3119	Returns string containing the guest stack for the selected VCPU on success.
3120	Returns None on failure.
3121	"""
3122
3123	#
3124	# Load all plugins first and try to detect the OS so we can
3125	# get nicer stack traces.
3126	#
3127	try:
3128	self.o.console.debugger.loadPlugIn('all');
3129	except:
3130	reporter.logXcpt('Unable to load debugger plugins');
3131	else:
3132	try:
3133	sOsDetected = self.o.console.debugger.detectOS();
3134	_ = sOsDetected;
3135	except:
3136	reporter.logXcpt('Failed to detect the guest OS');
3137
3138	sGuestStack = None;
3139	try:
3140	sGuestStack = self.o.console.debugger.dumpGuestStack(iCpu);
3141	except:
3142	reporter.logXcpt('Unable to query guest stack for CPU %s' % (iCpu, ));
3143
3144	return sGuestStack;
3145
3146
3147	#
3148	# Other methods.
3149	#
3150
3151	def getPrimaryIp(self):
3152	"""
3153	Tries to obtain the primary IP address of the guest via the guest
3154	properties.
3155
3156	Returns IP address on success.
3157	Returns empty string on failure.
3158	"""
3159	sIpAddr = self.getGuestPropertyValue('/VirtualBox/GuestInfo/Net/0/V4/IP');
3160	if vbox.isIpAddrValid(sIpAddr):
3161	return sIpAddr;
3162	return '';
3163
3164	def getPid(self):
3165	"""
3166	Gets the process ID for the direct session unless it's ourselves.
3167	"""
3168	if self.uPid is None and self.o is not None and self.fRemoteSession:
3169	try:
3170	if self.fpApiVer >= 4.2:
3171	uPid = self.o.machine.sessionPID;
3172	else:
3173	uPid = self.o.machine.sessionPid;
3174	if uPid != os.getpid() and uPid != 0xffffffff:
3175	self.uPid = uPid;
3176	except Exception as oXcpt:
3177	if vbox.ComError.equal(oXcpt, vbox.ComError.E_UNEXPECTED):
3178	try:
3179	if self.fpApiVer >= 4.2:
3180	uPid = self.oVM.sessionPID;
3181	else:
3182	uPid = self.oVM.sessionPid;
3183	if uPid != os.getpid() and uPid != 0xffffffff:
3184	self.uPid = uPid;
3185	except:
3186	reporter.log2Xcpt();
3187	else:
3188	reporter.log2Xcpt();
3189	if self.uPid is not None:
3190	reporter.log2('getPid: %u' % (self.uPid,));
3191	self.fPidFile = self.oTstDrv.pidFileAdd(self.uPid, 'vm_%s' % (self.sName,), # Set-uid-to-root is similar to SUDO.
3192	fSudo = True);
3193	return self.uPid;
3194
3195	def addLogsToReport(self, cReleaseLogs = 1):
3196	"""
3197	Retrieves and adds the release and debug logs to the test report.
3198	"""
3199	fRc = True;
3200
3201	# Add each of the requested release logs to the report.
3202	for iLog in range(0, cReleaseLogs):
3203	try:
3204	if self.fpApiVer >= 3.2:
3205	sLogFile = self.oVM.queryLogFilename(iLog);
3206	elif iLog > 0:
3207	sLogFile = '%s/VBox.log' % (self.oVM.logFolder,);
3208	else:
3209	sLogFile = '%s/VBox.log.%u' % (self.oVM.logFolder, iLog);
3210	except:
3211	reporter.logXcpt('iLog=%s' % (iLog,));
3212	fRc = False;
3213	else:
3214	if sLogFile is not None and sLogFile != '': # the None bit is for a 3.2.0 bug.
3215	reporter.addLogFile(sLogFile, 'log/release/vm', '%s #%u' % (self.sName, iLog),
3216	sAltName = '%s-%s' % (self.sName, os.path.basename(sLogFile),));
3217
3218	# Now for the hardened windows startup log.
3219	try:
3220	sLogFile = os.path.join(self.oVM.logFolder, 'VBoxHardening.log');
3221	except:
3222	reporter.logXcpt();
3223	fRc = False;
3224	else:
3225	if os.path.isfile(sLogFile):
3226	reporter.addLogFile(sLogFile, 'log/release/vm', '%s hardening log' % (self.sName, ),
3227	sAltName = '%s-%s' % (self.sName, os.path.basename(sLogFile),));
3228
3229	# Now for the debug log.
3230	if self.sLogFile is not None and os.path.isfile(self.sLogFile):
3231	reporter.addLogFile(self.sLogFile, 'log/debug/vm', '%s debug' % (self.sName, ),
3232	sAltName = '%s-%s' % (self.sName, os.path.basename(self.sLogFile),));
3233
3234	return fRc;
3235
3236	def registerDerivedEventHandler(self, oSubClass, dArgs = None, fMustSucceed = True):
3237	"""
3238	Create an instance of the given ConsoleEventHandlerBase sub-class and
3239	register it.
3240
3241	The new instance is returned on success. None is returned on error.
3242	"""
3243
3244	# We need a console object.
3245	try:
3246	oConsole = self.o.console;
3247	except Exception as oXcpt:
3248	if fMustSucceed or vbox.ComError.notEqual(oXcpt, vbox.ComError.E_UNEXPECTED):
3249	reporter.errorXcpt('Failed to get ISession::console for "%s"' % (self.sName, ));
3250	return None;
3251
3252	# Add the base class arguments.
3253	dArgsCopy = dArgs.copy() if dArgs is not None else {};
3254	dArgsCopy['oSession'] = self;
3255	dArgsCopy['oConsole'] = oConsole;
3256	sLogSuffix = 'on %s' % (self.sName,)
3257	return oSubClass.registerDerivedEventHandler(self.oVBoxMgr, self.fpApiVer, oSubClass, dArgsCopy,
3258	oConsole, 'IConsole', 'IConsoleCallback',
3259	fMustSucceed = fMustSucceed, sLogSuffix = sLogSuffix);
3260
3261	def enableVmmDevTestingPart(self, fEnabled, fEnableMMIO = False):
3262	"""
3263	Enables the testing part of the VMMDev.
3264
3265	Returns True on success and False on failure. Error information is logged.
3266	"""
3267	fRc = True;
3268	try:
3269	self.o.machine.setExtraData('VBoxInternal/Devices/VMMDev/0/Config/TestingEnabled',
3270	'1' if fEnabled else '');
3271	self.o.machine.setExtraData('VBoxInternal/Devices/VMMDev/0/Config/TestingMMIO',
3272	'1' if fEnableMMIO and fEnabled else '');
3273	except:
3274	reporter.errorXcpt('VM name "%s", fEnabled=%s' % (self.sName, fEnabled));
3275	fRc = False;
3276	else:
3277	reporter.log('set VMMDevTesting=%s for "%s"' % (fEnabled, self.sName));
3278	self.oTstDrv.processPendingEvents();
3279	return fRc;
3280
3281	#
3282	# Test eXecution Service methods.
3283	#
3284
3285	def txsConnectViaTcp(self, cMsTimeout = 10*60000, sIpAddr = None, fNatForwardingForTxs = False):
3286	"""
3287	Connects to the TXS using TCP/IP as transport. If no IP or MAC is
3288	addresses are specified, we'll get the IP from the guest additions.
3289
3290	Returns a TxsConnectTask object on success, None + log on failure.
3291	"""
3292	# If the VM is configured with a NAT interface, connect to local host.
3293	fReversedSetup = False;
3294	fUseNatForTxs = False;
3295	sMacAddr = None;
3296	oIDhcpServer = None;
3297	if sIpAddr is None:
3298	try:
3299	oNic = self.oVM.getNetworkAdapter(0);
3300	enmAttachmentType = oNic.attachmentType;
3301	if enmAttachmentType == vboxcon.NetworkAttachmentType_NAT:
3302	fUseNatForTxs = True;
3303	elif enmAttachmentType == vboxcon.NetworkAttachmentType_HostOnly and not sIpAddr:
3304	# Get the MAC address and find the DHCP server.
3305	sMacAddr = oNic.MACAddress;
3306	sHostOnlyNIC = oNic.hostOnlyInterface;
3307	oIHostOnlyIf = self.oVBox.host.findHostNetworkInterfaceByName(sHostOnlyNIC);
3308	sHostOnlyNet = oIHostOnlyIf.networkName;
3309	oIDhcpServer = self.oVBox.findDHCPServerByNetworkName(sHostOnlyNet);
3310	except:
3311	reporter.errorXcpt();
3312	return None;
3313
3314	if fUseNatForTxs:
3315	fReversedSetup = not fNatForwardingForTxs;
3316	sIpAddr = '127.0.0.1';
3317
3318	# Kick off the task.
3319	try:
3320	oTask = TxsConnectTask(self, cMsTimeout, sIpAddr, sMacAddr, oIDhcpServer, fReversedSetup,
3321	fnProcessEvents = self.oTstDrv.processPendingEvents);
3322	except:
3323	reporter.errorXcpt();
3324	oTask = None;
3325	return oTask;
3326
3327	def txsTryConnectViaTcp(self, cMsTimeout, sHostname, fReversed = False):
3328	"""
3329	Attempts to connect to a TXS instance.
3330
3331	Returns True if a connection was established, False if not (only grave
3332	failures are logged as errors).
3333
3334	Note! The timeout is more of a guideline...
3335	"""
3336
3337	if sHostname is None or sHostname.strip() == '':
3338	raise base.GenError('Empty sHostname is not implemented yet');
3339
3340	oTxsSession = txsclient.tryOpenTcpSession(cMsTimeout, sHostname, fReversedSetup = fReversed,
3341	cMsIdleFudge = cMsTimeout // 2,
3342	fnProcessEvents = self.oTstDrv.processPendingEvents);
3343	if oTxsSession is None:
3344	return False;
3345
3346	# Wait for the connect task to time out.
3347	self.oTstDrv.addTask(oTxsSession);
3348	self.oTstDrv.processPendingEvents();
3349	oRc = self.oTstDrv.waitForTasks(cMsTimeout);
3350	self.oTstDrv.removeTask(oTxsSession);
3351	if oRc != oTxsSession:
3352	if oRc is not None:
3353	reporter.log('oRc=%s, expected %s' % (oRc, oTxsSession));
3354	self.oTstDrv.processPendingEvents();
3355	oTxsSession.cancelTask(); # this is synchronous
3356	return False;
3357
3358	# Check the status.
3359	reporter.log2('TxsSession is ready, isSuccess() -> %s.' % (oTxsSession.isSuccess(),));
3360	if not oTxsSession.isSuccess():
3361	return False;
3362
3363	reporter.log2('Disconnecting from TXS...');
3364	return oTxsSession.syncDisconnect();
3365
3366
3367
3368	class TxsConnectTask(TdTaskBase):
3369	"""
3370	Class that takes care of connecting to a VM.
3371	"""
3372
3373	class TxsConnectTaskVBoxCallback(vbox.VirtualBoxEventHandlerBase):
3374	""" Class for looking for IPv4 address changes on interface 0."""
3375	def __init__(self, dArgs):
3376	vbox.VirtualBoxEventHandlerBase.__init__(self, dArgs);
3377	self.oParentTask = dArgs['oParentTask'];
3378	self.sMachineId = dArgs['sMachineId'];
3379
3380	def onGuestPropertyChange(self, sMachineId, sName, sValue, sFlags, fWasDeleted):
3381	"""Look for IP address."""
3382	reporter.log2('onGuestPropertyChange(,%s,%s,%s,%s,%s)' % (sMachineId, sName, sValue, sFlags, fWasDeleted));
3383	if sMachineId == self.sMachineId \
3384	and sName == '/VirtualBox/GuestInfo/Net/0/V4/IP':
3385	oParentTask = self.oParentTask;
3386	if oParentTask:
3387	oParentTask._setIp(sValue); # pylint: disable=protected-access
3388
3389
3390	def __init__(self, oSession, cMsTimeout, sIpAddr, sMacAddr, oIDhcpServer, fReversedSetup, fnProcessEvents = None):
3391	TdTaskBase.__init__(self, utils.getCallerName(), fnProcessEvents = fnProcessEvents);
3392	self.cMsTimeout = cMsTimeout;
3393	self.fnProcessEvents = fnProcessEvents;
3394	self.sIpAddr = None;
3395	self.sNextIpAddr = None;
3396	self.sMacAddr = sMacAddr;
3397	self.oIDhcpServer = oIDhcpServer;
3398	self.fReversedSetup = fReversedSetup;
3399	self.oVBoxEventHandler = None;
3400	self.oTxsSession = None;
3401
3402	# Check that the input makes sense:
3403	if (sMacAddr is None) != (oIDhcpServer is None) \
3404	or (sMacAddr and fReversedSetup) \
3405	or (sMacAddr and sIpAddr):
3406	reporter.error('TxsConnectTask sMacAddr=%s oIDhcpServer=%s sIpAddr=%s fReversedSetup=%s'
3407	% (sMacAddr, oIDhcpServer, sIpAddr, fReversedSetup,));
3408	raise base.GenError();
3409
3410	reporter.log2('TxsConnectTask: sIpAddr=%s fReversedSetup=%s' % (sIpAddr, fReversedSetup))
3411	if fReversedSetup is True:
3412	self._openTcpSession(sIpAddr, fReversedSetup = True);
3413	elif sIpAddr is not None and sIpAddr.strip() != '':
3414	self._openTcpSession(sIpAddr, cMsIdleFudge = 5000);
3415	else:
3416	#
3417	# If we've got no IP address, register callbacks that listens for
3418	# the primary network adaptor of the VM to set a IPv4 guest prop.
3419	# Note! The order in which things are done here is kind of important.
3420	#
3421
3422	# 0. The caller zaps the property before starting the VM.
3423	#try:
3424	# oSession.delGuestPropertyValue('/VirtualBox/GuestInfo/Net/0/V4/IP');
3425	#except:
3426	# reporter.logXcpt();
3427
3428	# 1. Register the callback / event listener object.
3429	dArgs = {'oParentTask':self, 'sMachineId':oSession.o.machine.id};
3430	self.oVBoxEventHandler = oSession.oVBox.registerDerivedEventHandler(self.TxsConnectTaskVBoxCallback, dArgs);
3431
3432	# 2. Query the guest properties.
3433	try:
3434	sIpAddr = oSession.getGuestPropertyValue('/VirtualBox/GuestInfo/Net/0/V4/IP');
3435	except:
3436	reporter.errorXcpt('IMachine::getGuestPropertyValue("/VirtualBox/GuestInfo/Net/0/V4/IP") failed');
3437	self._deregisterEventHandler();
3438	raise;
3439	if sIpAddr is not None:
3440	self._setIp(sIpAddr);
3441
3442	#
3443	# If the network adapter of the VM is host-only we can talk poll IDHCPServer
3444	# for the guest IP, allowing us to detect it for VMs without guest additions.
3445	# This will when we're polled.
3446	#
3447	if sMacAddr is not None:
3448	assert self.oIDhcpServer is not None;
3449
3450
3451	# end __init__
3452
3453	def __del__(self):
3454	""" Make sure we deregister the callback. """
3455	self._deregisterEventHandler();
3456	return TdTaskBase.__del__(self);
3457
3458	def toString(self):
3459	return '<%s cMsTimeout=%s, sIpAddr=%s, sNextIpAddr=%s, sMacAddr=%s, fReversedSetup=%s,' \
3460	' oTxsSession=%s oVBoxEventHandler=%s>' \
3461	% (TdTaskBase.toString(self), self.cMsTimeout, self.sIpAddr, self.sNextIpAddr, self.sMacAddr, self.fReversedSetup,
3462	self.oTxsSession, self.oVBoxEventHandler);
3463
3464	def _deregisterEventHandler(self):
3465	"""Deregisters the event handler."""
3466	fRc = True;
3467	oVBoxEventHandler = self.oVBoxEventHandler;
3468	if oVBoxEventHandler is not None:
3469	self.oVBoxEventHandler = None;
3470	fRc = oVBoxEventHandler.unregister();
3471	oVBoxEventHandler.oParentTask = None; # Try avoid cylic deps.
3472	return fRc;
3473
3474	def _setIp(self, sIpAddr, fInitCall = False):
3475	"""Called when we get an IP. Will create a TXS session and signal the task."""
3476	sIpAddr = sIpAddr.strip();
3477
3478	if sIpAddr is not None \
3479	and sIpAddr != '':
3480	if vbox.isIpAddrValid(sIpAddr) or fInitCall:
3481	try:
3482	for s in sIpAddr.split('.'):
3483	i = int(s);
3484	if str(i) != s:
3485	raise Exception();
3486	except:
3487	reporter.fatalXcpt();
3488	else:
3489	reporter.log('TxsConnectTask: opening session to ip "%s"' % (sIpAddr));
3490	self._openTcpSession(sIpAddr, cMsIdleFudge = 5000);
3491	return None;
3492
3493	reporter.log('TxsConnectTask: Ignoring Bad ip "%s"' % (sIpAddr));
3494	else:
3495	reporter.log2('TxsConnectTask: Ignoring empty ip "%s"' % (sIpAddr));
3496	return None;
3497
3498	def _openTcpSession(self, sIpAddr, uPort = None, fReversedSetup = False, cMsIdleFudge = 0):
3499	"""
3500	Calls txsclient.openTcpSession and switches our task to reflect the
3501	state of the subtask.
3502	"""
3503	self.oCv.acquire();
3504	if self.oTxsSession is None:
3505	reporter.log2('_openTcpSession: sIpAddr=%s, uPort=%d, fReversedSetup=%s' %
3506	(sIpAddr, uPort if uPort is not None else 0, fReversedSetup));
3507	self.sIpAddr = sIpAddr;
3508	self.oTxsSession = txsclient.openTcpSession(self.cMsTimeout, sIpAddr, uPort, fReversedSetup,
3509	cMsIdleFudge, fnProcessEvents = self.fnProcessEvents);
3510	self.oTxsSession.setTaskOwner(self);
3511	else:
3512	self.sNextIpAddr = sIpAddr;
3513	reporter.log2('_openTcpSession: sNextIpAddr=%s' % (sIpAddr,));
3514	self.oCv.release();
3515	return None;
3516
3517	def notifyAboutReadyTask(self, oTxsSession):
3518	"""
3519	Called by the TXS session task when it's done.
3520
3521	We'll signal the task completed or retry depending on the result.
3522	"""
3523
3524	self.oCv.acquire();
3525
3526	# Disassociate ourselves with the session (avoid cyclic ref)
3527	oTxsSession.setTaskOwner(None);
3528	fSuccess = oTxsSession.isSuccess();
3529	if self.oTxsSession is not None:
3530	if not fSuccess:
3531	self.oTxsSession = None;
3532	if fSuccess and self.fReversedSetup:
3533	self.sIpAddr = oTxsSession.oTransport.sHostname;
3534	else:
3535	fSuccess = False;
3536
3537	# Signal done, or retry?
3538	fDeregister = False;
3539	if fSuccess \
3540	or self.fReversedSetup \
3541	or self.getAgeAsMs() >= self.cMsTimeout:
3542	self.signalTaskLocked();
3543	fDeregister = True;
3544	else:
3545	sIpAddr = self.sNextIpAddr if self.sNextIpAddr is not None else self.sIpAddr;
3546	self._openTcpSession(sIpAddr, cMsIdleFudge = 5000);
3547
3548	self.oCv.release();
3549
3550	# If we're done, deregister the callback (w/o owning lock). It will
3551	if fDeregister:
3552	self._deregisterEventHandler();
3553	return True;
3554
3555	def _pollDhcpServer(self):
3556	"""
3557	Polls the DHCP server by MAC address in host-only setups.
3558	"""
3559
3560	if self.sIpAddr:
3561	return False;
3562
3563	if self.oIDhcpServer is None or not self.sMacAddr:
3564	return False;
3565
3566	try:
3567	(sIpAddr, sState, secIssued, secExpire) = self.oIDhcpServer.findLeaseByMAC(self.sMacAddr, 0);
3568	except:
3569	reporter.log4Xcpt('sMacAddr=%s' % (self.sMacAddr,));
3570	return False;
3571
3572	secNow = utils.secondsSinceUnixEpoch();
3573	reporter.log2('dhcp poll: secNow=%s secExpire=%s secIssued=%s sState=%s sIpAddr=%s'
3574	% (secNow, secExpire, secIssued, sState, sIpAddr,));
3575	if secNow > secExpire or sState != 'acked' or not sIpAddr:
3576	return False;
3577
3578	reporter.log('dhcp poll: sIpAddr=%s secExpire=%s (%s TTL) secIssued=%s (%s ago)'
3579	% (sIpAddr, secExpire, secExpire - secNow, secIssued, secNow - secIssued,));
3580	self._setIp(sIpAddr);
3581	return True;
3582
3583	#
3584	# Task methods
3585	#
3586
3587	def pollTask(self, fLocked = False):
3588	"""
3589	Overridden pollTask method.
3590	"""
3591	self._pollDhcpServer();
3592	return TdTaskBase.pollTask(self, fLocked);
3593
3594	#
3595	# Public methods
3596	#
3597
3598	def getResult(self):
3599	"""
3600	Returns the connected TXS session object on success.
3601	Returns None on failure or if the task has not yet completed.
3602	"""
3603	self.oCv.acquire();
3604	oTxsSession = self.oTxsSession;
3605	self.oCv.release();
3606
3607	if oTxsSession is not None and not oTxsSession.isSuccess():
3608	oTxsSession = None;
3609	return oTxsSession;
3610
3611	def cancelTask(self):
3612	""" Cancels the task. """
3613	self._deregisterEventHandler(); # (make sure to avoid cyclic fun)
3614	self.oCv.acquire();
3615	if not self.fSignalled:
3616	oTxsSession = self.oTxsSession;
3617	if oTxsSession is not None:
3618	self.oCv.release();
3619	oTxsSession.setTaskOwner(None);
3620	oTxsSession.cancelTask();
3621	oTxsSession.waitForTask(1000);
3622	self.oCv.acquire();
3623	self.signalTaskLocked();
3624	self.oCv.release();
3625	return True;
3626
3627
3628
3629	class AdditionsStatusTask(TdTaskBase):
3630	"""
3631	Class that takes care of waiting till the guest additions are in a given state.
3632	"""
3633
3634	class AdditionsStatusTaskCallback(vbox.EventHandlerBase):
3635	""" Class for looking for IPv4 address changes on interface 0."""
3636	def __init__(self, dArgs):
3637	self.oParentTask = dArgs['oParentTask'];
3638	vbox.EventHandlerBase.__init__(self, dArgs, self.oParentTask.oSession.fpApiVer,
3639	'AdditionsStatusTaskCallback/%s' % (self.oParentTask.oSession.sName,));
3640
3641	def handleEvent(self, oEvt):
3642	try:
3643	enmType = oEvt.type;
3644	except:
3645	reporter.errorXcpt();
3646	else:
3647	reporter.log2('AdditionsStatusTaskCallback:handleEvent: enmType=%s' % (enmType,));
3648	if enmType == vboxcon.VBoxEventType_OnGuestAdditionsStatusChanged:
3649	oParentTask = self.oParentTask;
3650	if oParentTask:
3651	oParentTask.pollTask();
3652
3653	# end
3654
3655
3656	def __init__(self, oSession, oIGuest, cMsTimeout = 120000, aenmWaitForRunLevels = None, aenmWaitForActive = None,
3657	aenmWaitForInactive = None):
3658	"""
3659	aenmWaitForRunLevels - List of run level values to wait for (success if one matches).
3660	aenmWaitForActive - List facilities (type values) that must be active.
3661	aenmWaitForInactive - List facilities (type values) that must be inactive.
3662
3663	The default is to wait for AdditionsRunLevelType_Userland if all three lists
3664	are unspecified or empty.
3665	"""
3666	TdTaskBase.__init__(self, utils.getCallerName());
3667	self.oSession = oSession # type: vboxwrappers.SessionWrapper
3668	self.oIGuest = oIGuest;
3669	self.cMsTimeout = cMsTimeout;
3670	self.fSucceeded = False;
3671	self.oVBoxEventHandler = None;
3672	self.aenmWaitForRunLevels = aenmWaitForRunLevels if aenmWaitForRunLevels else [];
3673	self.aenmWaitForActive = aenmWaitForActive if aenmWaitForActive else [];
3674	self.aenmWaitForInactive = aenmWaitForInactive if aenmWaitForInactive else [];
3675
3676	# Provide a sensible default if nothing is given.
3677	if not self.aenmWaitForRunLevels and not self.aenmWaitForActive and not self.aenmWaitForInactive:
3678	self.aenmWaitForRunLevels = [vboxcon.AdditionsRunLevelType_Userland,];
3679
3680	# Register the event handler on hosts which has it:
3681	if oSession.fpApiVer >= 6.1 or hasattr(vboxcon, 'VBoxEventType_OnGuestAdditionsStatusChanged'):
3682	aenmEvents = (vboxcon.VBoxEventType_OnGuestAdditionsStatusChanged,);
3683	dArgs = {
3684	'oParentTask': self,
3685	};
3686	self.oVBoxEventHandler = vbox.EventHandlerBase.registerDerivedEventHandler(oSession.oVBoxMgr,
3687	oSession.fpApiVer,
3688	self.AdditionsStatusTaskCallback,
3689	dArgs,
3690	oIGuest,
3691	'IGuest',
3692	'AdditionsStatusTaskCallback',
3693	aenmEvents = aenmEvents);
3694	reporter.log2('AdditionsStatusTask: %s' % (self.toString(), ));
3695
3696	def __del__(self):
3697	""" Make sure we deregister the callback. """
3698	self._deregisterEventHandler();
3699	self.oIGuest = None;
3700	return TdTaskBase.__del__(self);
3701
3702	def toString(self):
3703	return '<%s cMsTimeout=%s, fSucceeded=%s, aenmWaitForRunLevels=%s, aenmWaitForActive=%s, aenmWaitForInactive=%s, ' \
3704	'oVBoxEventHandler=%s>' \
3705	% (TdTaskBase.toString(self), self.cMsTimeout, self.fSucceeded, self.aenmWaitForRunLevels, self.aenmWaitForActive,
3706	self.aenmWaitForInactive, self.oVBoxEventHandler,);
3707
3708	def _deregisterEventHandler(self):
3709	"""Deregisters the event handler."""
3710	fRc = True;
3711	oVBoxEventHandler = self.oVBoxEventHandler;
3712	if oVBoxEventHandler is not None:
3713	self.oVBoxEventHandler = None;
3714	fRc = oVBoxEventHandler.unregister();
3715	oVBoxEventHandler.oParentTask = None; # Try avoid cylic deps.
3716	return fRc;
3717
3718	def _poll(self):
3719	"""
3720	Internal worker for pollTask() that returns the new signalled state.
3721	"""
3722
3723	#
3724	# Check if any of the runlevels we wait for have been reached:
3725	#
3726	if self.aenmWaitForRunLevels:
3727	try:
3728	enmRunLevel = self.oIGuest.additionsRunLevel;
3729	except:
3730	reporter.errorXcpt();
3731	return True;
3732	if enmRunLevel not in self.aenmWaitForRunLevels:
3733	reporter.log6('AdditionsStatusTask/poll: enmRunLevel=%s not in %s' % (enmRunLevel, self.aenmWaitForRunLevels,));
3734	return False;
3735	reporter.log2('AdditionsStatusTask/poll: enmRunLevel=%s matched %s!' % (enmRunLevel, self.aenmWaitForRunLevels,));
3736
3737
3738	#
3739	# Check for the facilities that must all be active.
3740	#
3741	for enmFacility in self.aenmWaitForActive:
3742	try:
3743	(enmStatus, _) = self.oIGuest.getFacilityStatus(enmFacility);
3744	except:
3745	reporter.errorXcpt('enmFacility=%s' % (enmFacility,));
3746	return True;
3747	if enmStatus != vboxcon.AdditionsFacilityStatus_Active:
3748	reporter.log2('AdditionsStatusTask/poll: enmFacility=%s not active: %s' % (enmFacility, enmStatus,));
3749	return False;
3750
3751	#
3752	# Check for the facilities that must all be inactive or terminated.
3753	#
3754	for enmFacility in self.aenmWaitForInactive:
3755	try:
3756	(enmStatus, _) = self.oIGuest.getFacilityStatus(enmFacility);
3757	except:
3758	reporter.errorXcpt('enmFacility=%s' % (enmFacility,));
3759	return True;
3760	if enmStatus not in (vboxcon.AdditionsFacilityStatus_Inactive,
3761	vboxcon.AdditionsFacilityStatus_Terminated):
3762	reporter.log2('AdditionsStatusTask/poll: enmFacility=%s not inactive: %s' % (enmFacility, enmStatus,));
3763	return False;
3764
3765
3766	reporter.log('AdditionsStatusTask: Poll succeeded, signalling...');
3767	self.fSucceeded = True;
3768	return True;
3769
3770
3771	#
3772	# Task methods
3773	#
3774
3775	def pollTask(self, fLocked = False):
3776	"""
3777	Overridden pollTask method.
3778	"""
3779	if not fLocked:
3780	self.lockTask();
3781
3782	fDeregister = False;
3783	fRc = self.fSignalled;
3784	if not fRc:
3785	fRc = self._poll();
3786	if fRc or self.getAgeAsMs() >= self.cMsTimeout:
3787	self.signalTaskLocked();
3788	fDeregister = True;
3789
3790	if not fLocked:
3791	self.unlockTask();
3792
3793	# If we're done, deregister the event callback (w/o owning lock).
3794	if fDeregister:
3795	self._deregisterEventHandler();
3796	return fRc;
3797
3798	def getResult(self):
3799	"""
3800	Returns true if the we succeeded.
3801	Returns false if not. If the task is signalled already, then we
3802	encountered a problem while polling.
3803	"""
3804	return self.fSucceeded;
3805
3806	def cancelTask(self):
3807	"""
3808	Cancels the task.
3809	Just to actively disengage the event handler.
3810	"""
3811	self._deregisterEventHandler();
3812	return True;

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: vbox/trunk/src/VBox/ValidationKit/testdriver/vboxwrappers.py

Download in other formats: