DBGF.cpp@ 61766

Last change on this file since 61766 was 61766, checked in by vboxsync, 8 years ago
doxygen fix
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 54.2 KB

Line
1	/* $Id: DBGF.cpp 61766 2016-06-20 10:48:51Z vboxsync $ */
2	/** @file
3	* DBGF - Debugger Facility.
4	*/
5
6	/*
7	* Copyright (C) 2006-2015 Oracle Corporation
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*/
17
18
19	/** @page pg_dbgf DBGF - The Debugger Facility
20	*
21	* The purpose of the DBGF is to provide an interface for debuggers to
22	* manipulate the VMM without having to mess up the source code for each of
23	* them. The DBGF is always built in and will always work when a debugger
24	* attaches to the VM. The DBGF provides the basic debugger features, such as
25	* halting execution, handling breakpoints, single step execution, instruction
26	* disassembly, info querying, OS specific diggers, symbol and module
27	* management.
28	*
29	* The interface is working in a manner similar to the win32, linux and os2
30	* debugger interfaces. The interface has an asynchronous nature. This comes
31	* from the fact that the VMM and the Debugger are running in different threads.
32	* They are referred to as the "emulation thread" and the "debugger thread", or
33	* as the "ping thread" and the "pong thread, respectivly. (The last set of
34	* names comes from the use of the Ping-Pong synchronization construct from the
35	* RTSem API.)
36	*
37	* @see grp_dbgf
38	*
39	*
40	* @section sec_dbgf_scenario Usage Scenario
41	*
42	* The debugger starts by attaching to the VM. For practical reasons we limit the
43	* number of concurrently attached debuggers to 1 per VM. The action of
44	* attaching to the VM causes the VM to check and generate debug events.
45	*
46	* The debugger then will wait/poll for debug events and issue commands.
47	*
48	* The waiting and polling is done by the DBGFEventWait() function. It will wait
49	* for the emulation thread to send a ping, thus indicating that there is an
50	* event waiting to be processed.
51	*
52	* An event can be a response to a command issued previously, the hitting of a
53	* breakpoint, or running into a bad/fatal VMM condition. The debugger now has
54	* the ping and must respond to the event at hand - the VMM is waiting. This
55	* usually means that the user of the debugger must do something, but it doesn't
56	* have to. The debugger is free to call any DBGF function (nearly at least)
57	* while processing the event.
58	*
59	* Typically the user will issue a request for the execution to be resumed, so
60	* the debugger calls DBGFResume() and goes back to waiting/polling for events.
61	*
62	* When the user eventually terminates the debugging session or selects another
63	* VM, the debugger detaches from the VM. This means that breakpoints are
64	* disabled and that the emulation thread no longer polls for debugger commands.
65	*
66	*/
67
68
69	/*********************************************************************************************************************************
70	* Header Files *
71	*********************************************************************************************************************************/
72	#define LOG_GROUP LOG_GROUP_DBGF
73	#include <VBox/vmm/dbgf.h>
74	#include <VBox/vmm/selm.h>
75	#ifdef VBOX_WITH_REM
76	# include <VBox/vmm/rem.h>
77	#endif
78	#include <VBox/vmm/em.h>
79	#include <VBox/vmm/hm.h>
80	#include "DBGFInternal.h"
81	#include <VBox/vmm/vm.h>
82	#include <VBox/vmm/uvm.h>
83	#include <VBox/err.h>
84
85	#include <VBox/log.h>
86	#include <iprt/semaphore.h>
87	#include <iprt/thread.h>
88	#include <iprt/asm.h>
89	#include <iprt/time.h>
90	#include <iprt/assert.h>
91	#include <iprt/stream.h>
92	#include <iprt/env.h>
93
94
95	/*********************************************************************************************************************************
96	* Internal Functions *
97	*********************************************************************************************************************************/
98	static int dbgfR3VMMWait(PVM pVM);
99	static int dbgfR3VMMCmd(PVM pVM, DBGFCMD enmCmd, PDBGFCMDDATA pCmdData, bool *pfResumeExecution);
100	static DECLCALLBACK(int) dbgfR3Attach(PVM pVM);
101
102
103	/**
104	* Sets the VMM Debug Command variable.
105	*
106	* @returns Previous command.
107	* @param pVM The cross context VM structure.
108	* @param enmCmd The command.
109	*/
110	DECLINLINE(DBGFCMD) dbgfR3SetCmd(PVM pVM, DBGFCMD enmCmd)
111	{
112	DBGFCMD rc;
113	if (enmCmd == DBGFCMD_NO_COMMAND)
114	{
115	Log2(("DBGF: Setting command to %d (DBGFCMD_NO_COMMAND)\n", enmCmd));
116	rc = (DBGFCMD)ASMAtomicXchgU32((uint32_t volatile )(void )&pVM->dbgf.s.enmVMMCmd, enmCmd);
117	VM_FF_CLEAR(pVM, VM_FF_DBGF);
118	}
119	else
120	{
121	Log2(("DBGF: Setting command to %d\n", enmCmd));
122	AssertMsg(pVM->dbgf.s.enmVMMCmd == DBGFCMD_NO_COMMAND, ("enmCmd=%d enmVMMCmd=%d\n", enmCmd, pVM->dbgf.s.enmVMMCmd));
123	rc = (DBGFCMD)ASMAtomicXchgU32((uint32_t volatile )(void )&pVM->dbgf.s.enmVMMCmd, enmCmd);
124	VM_FF_SET(pVM, VM_FF_DBGF);
125	VMR3NotifyGlobalFFU(pVM->pUVM, 0 /* didn't notify REM */);
126	}
127	return rc;
128	}
129
130
131	/**
132	* Initializes the DBGF.
133	*
134	* @returns VBox status code.
135	* @param pVM The cross context VM structure.
136	*/
137	VMMR3_INT_DECL(int) DBGFR3Init(PVM pVM)
138	{
139	PUVM pUVM = pVM->pUVM;
140	AssertCompile(sizeof(pUVM->dbgf.s) <= sizeof(pUVM->dbgf.padding));
141	AssertCompile(sizeof(pUVM->aCpus[0].dbgf.s) <= sizeof(pUVM->aCpus[0].dbgf.padding));
142
143	/*
144	* The usual sideways mountain climbing style of init:
145	*/
146	int rc = dbgfR3InfoInit(pUVM); /* (First, initalizes the shared critical section.) */
147	if (RT_SUCCESS(rc))
148	{
149	rc = dbgfR3TraceInit(pVM);
150	if (RT_SUCCESS(rc))
151	{
152	rc = dbgfR3RegInit(pUVM);
153	if (RT_SUCCESS(rc))
154	{
155	rc = dbgfR3AsInit(pUVM);
156	if (RT_SUCCESS(rc))
157	{
158	rc = dbgfR3BpInit(pVM);
159	if (RT_SUCCESS(rc))
160	{
161	rc = dbgfR3OSInit(pUVM);
162	if (RT_SUCCESS(rc))
163	{
164	rc = dbgfR3PlugInInit(pUVM);
165	if (RT_SUCCESS(rc))
166	{
167	return VINF_SUCCESS;
168	}
169	dbgfR3OSTerm(pUVM);
170	}
171	}
172	dbgfR3AsTerm(pUVM);
173	}
174	dbgfR3RegTerm(pUVM);
175	}
176	dbgfR3TraceTerm(pVM);
177	}
178	dbgfR3InfoTerm(pUVM);
179	}
180	return rc;
181	}
182
183
184	/**
185	* Terminates and cleans up resources allocated by the DBGF.
186	*
187	* @returns VBox status code.
188	* @param pVM The cross context VM structure.
189	*/
190	VMMR3_INT_DECL(int) DBGFR3Term(PVM pVM)
191	{
192	PUVM pUVM = pVM->pUVM;
193
194	dbgfR3PlugInTerm(pUVM);
195	dbgfR3OSTerm(pUVM);
196	dbgfR3AsTerm(pUVM);
197	dbgfR3RegTerm(pUVM);
198	dbgfR3TraceTerm(pVM);
199	dbgfR3InfoTerm(pUVM);
200
201	return VINF_SUCCESS;
202	}
203
204
205	/**
206	* Called when the VM is powered off to detach debuggers.
207	*
208	* @param pVM The cross context VM structure.
209	*/
210	VMMR3_INT_DECL(void) DBGFR3PowerOff(PVM pVM)
211	{
212
213	/*
214	* Send a termination event to any attached debugger.
215	*/
216	/* wait to become the speaker (we should already be that). */
217	if ( pVM->dbgf.s.fAttached
218	&& RTSemPingShouldWait(&pVM->dbgf.s.PingPong))
219	RTSemPingWait(&pVM->dbgf.s.PingPong, 5000);
220
221	if (pVM->dbgf.s.fAttached)
222	{
223	/* Just mark it as detached if we're not in a position to send a power
224	off event. It should fail later on. */
225	if (!RTSemPingIsSpeaker(&pVM->dbgf.s.PingPong))
226	{
227	ASMAtomicWriteBool(&pVM->dbgf.s.fAttached, false);
228	if (RTSemPingIsSpeaker(&pVM->dbgf.s.PingPong))
229	ASMAtomicWriteBool(&pVM->dbgf.s.fAttached, true);
230	}
231
232	if (RTSemPingIsSpeaker(&pVM->dbgf.s.PingPong))
233	{
234	/* Try send the power off event. */
235	int rc;
236	DBGFCMD enmCmd = dbgfR3SetCmd(pVM, DBGFCMD_NO_COMMAND);
237	if (enmCmd == DBGFCMD_DETACH_DEBUGGER)
238	/* the debugger beat us to initiating the detaching. */
239	rc = VINF_SUCCESS;
240	else
241	{
242	/* ignore the command (if any). */
243	enmCmd = DBGFCMD_NO_COMMAND;
244	pVM->dbgf.s.DbgEvent.enmType = DBGFEVENT_POWERING_OFF;
245	pVM->dbgf.s.DbgEvent.enmCtx = DBGFEVENTCTX_OTHER;
246	rc = RTSemPing(&pVM->dbgf.s.PingPong);
247	}
248
249	/*
250	* Process commands and priority requests until we get a command
251	* indicating that the debugger has detached.
252	*/
253	uint32_t cPollHack = 1;
254	PVMCPU pVCpu = VMMGetCpu(pVM);
255	while (RT_SUCCESS(rc))
256	{
257	if (enmCmd != DBGFCMD_NO_COMMAND)
258	{
259	/* process command */
260	bool fResumeExecution;
261	DBGFCMDDATA CmdData = pVM->dbgf.s.VMMCmdData;
262	rc = dbgfR3VMMCmd(pVM, enmCmd, &CmdData, &fResumeExecution);
263	if (enmCmd == DBGFCMD_DETACHED_DEBUGGER)
264	break;
265	enmCmd = DBGFCMD_NO_COMMAND;
266	}
267	else
268	{
269	/* Wait for new command, processing pending priority requests
270	first. The request processing is a bit crazy, but
271	unfortunately required by plugin unloading. */
272	if ( VM_FF_IS_PENDING(pVM, VM_FF_REQUEST)
273	\|\| VMCPU_FF_IS_PENDING(pVCpu, VMCPU_FF_REQUEST))
274	{
275	LogFlow(("DBGFR3PowerOff: Processes priority requests...\n"));
276	rc = VMR3ReqProcessU(pVM->pUVM, VMCPUID_ANY, true /fPriorityOnly/);
277	if (rc == VINF_SUCCESS)
278	rc = VMR3ReqProcessU(pVM->pUVM, pVCpu->idCpu, true /fPriorityOnly/);
279	LogFlow(("DBGFR3PowerOff: VMR3ReqProcess -> %Rrc\n", rc));
280	cPollHack = 1;
281	}
282	/* Need to handle rendezvous too, for generic debug event management. */
283	else if (VM_FF_IS_PENDING(pVM, VM_FF_EMT_RENDEZVOUS))
284	{
285	rc = VMMR3EmtRendezvousFF(pVM, pVCpu);
286	AssertLogRel(rc == VINF_SUCCESS);
287	cPollHack = 1;
288	}
289	else if (cPollHack < 120)
290	cPollHack++;
291
292	rc = RTSemPingWait(&pVM->dbgf.s.PingPong, cPollHack);
293	if (RT_SUCCESS(rc))
294	enmCmd = dbgfR3SetCmd(pVM, DBGFCMD_NO_COMMAND);
295	else if (rc == VERR_TIMEOUT)
296	rc = VINF_SUCCESS;
297	}
298	}
299
300	/*
301	* Clear the FF so we won't get confused later on.
302	*/
303	VM_FF_CLEAR(pVM, VM_FF_DBGF);
304	}
305	}
306	}
307
308
309	/**
310	* Applies relocations to data and code managed by this
311	* component. This function will be called at init and
312	* whenever the VMM need to relocate it self inside the GC.
313	*
314	* @param pVM The cross context VM structure.
315	* @param offDelta Relocation delta relative to old location.
316	*/
317	VMMR3_INT_DECL(void) DBGFR3Relocate(PVM pVM, RTGCINTPTR offDelta)
318	{
319	dbgfR3TraceRelocate(pVM);
320	dbgfR3AsRelocate(pVM->pUVM, offDelta);
321	}
322
323
324	/**
325	* Waits a little while for a debuggger to attach.
326	*
327	* @returns True is a debugger have attached.
328	* @param pVM The cross context VM structure.
329	* @param pVCpu The cross context per CPU structure.
330	* @param enmEvent Event.
331	*
332	* @thread EMT(pVCpu)
333	*/
334	bool dbgfR3WaitForAttach(PVM pVM, PVMCPU pVCpu, DBGFEVENTTYPE enmEvent)
335	{
336	/*
337	* First a message.
338	*/
339	#ifndef RT_OS_L4
340
341	# if !defined(DEBUG) \|\| defined(DEBUG_sandervl) \|\| defined(DEBUG_frank) \|\| defined(IEM_VERIFICATION_MODE)
342	int cWait = 10;
343	# else
344	int cWait = HMIsEnabled(pVM)
345	&& ( enmEvent == DBGFEVENT_ASSERTION_HYPER
346	\|\| enmEvent == DBGFEVENT_FATAL_ERROR)
347	&& !RTEnvExist("VBOX_DBGF_WAIT_FOR_ATTACH")
348	? 10
349	: 150;
350	# endif
351	RTStrmPrintf(g_pStdErr, "DBGF: No debugger attached, waiting %d second%s for one to attach (event=%d)\n",
352	cWait / 10, cWait != 10 ? "s" : "", enmEvent);
353	RTStrmFlush(g_pStdErr);
354	while (cWait > 0)
355	{
356	RTThreadSleep(100);
357	if (pVM->dbgf.s.fAttached)
358	{
359	RTStrmPrintf(g_pStdErr, "Attached!\n");
360	RTStrmFlush(g_pStdErr);
361	return true;
362	}
363
364	/* Process priority stuff. */
365	if ( VM_FF_IS_PENDING(pVM, VM_FF_REQUEST)
366	\|\| VMCPU_FF_IS_PENDING(pVCpu, VMCPU_FF_REQUEST))
367	{
368	int rc = VMR3ReqProcessU(pVM->pUVM, VMCPUID_ANY, true /fPriorityOnly/);
369	if (rc == VINF_SUCCESS)
370	rc = VMR3ReqProcessU(pVM->pUVM, pVCpu->idCpu, true /fPriorityOnly/);
371	if (rc != VINF_SUCCESS)
372	{
373	RTStrmPrintf(g_pStdErr, "[rcReq=%Rrc, ignored!]", rc);
374	RTStrmFlush(g_pStdErr);
375	}
376	}
377
378	/* next */
379	if (!(cWait % 10))
380	{
381	RTStrmPrintf(g_pStdErr, "%d.", cWait / 10);
382	RTStrmFlush(g_pStdErr);
383	}
384	cWait--;
385	}
386	#endif
387
388	RTStrmPrintf(g_pStdErr, "Stopping the VM!\n");
389	RTStrmFlush(g_pStdErr);
390	return false;
391	}
392
393
394	/**
395	* Forced action callback.
396	*
397	* The VMM will call this from it's main loop when either VM_FF_DBGF or
398	* VMCPU_FF_DBGF are set.
399	*
400	* The function checks for and executes pending commands from the debugger.
401	* Then it checks for pending debug events and serves these.
402	*
403	* @returns VINF_SUCCESS normally.
404	* @returns VERR_DBGF_RAISE_FATAL_ERROR to pretend a fatal error happened.
405	* @param pVM The cross context VM structure.
406	* @param pVCpu The cross context per CPU structure.
407	*/
408	VMMR3_INT_DECL(int) DBGFR3VMMForcedAction(PVM pVM, PVMCPU pVCpu)
409	{
410	VBOXSTRICTRC rcStrict = VINF_SUCCESS;
411
412	if (VM_FF_TEST_AND_CLEAR(pVM, VM_FF_DBGF))
413	{
414	/*
415	* Command pending? Process it.
416	*/
417	if (pVM->dbgf.s.enmVMMCmd != DBGFCMD_NO_COMMAND)
418	{
419	bool fResumeExecution;
420	DBGFCMDDATA CmdData = pVM->dbgf.s.VMMCmdData;
421	DBGFCMD enmCmd = dbgfR3SetCmd(pVM, DBGFCMD_NO_COMMAND);
422	rcStrict = dbgfR3VMMCmd(pVM, enmCmd, &CmdData, &fResumeExecution);
423	if (!fResumeExecution)
424	rcStrict = dbgfR3VMMWait(pVM);
425	}
426	}
427
428	/*
429	* Dispatch pending events.
430	*/
431	if (VMCPU_FF_TEST_AND_CLEAR(pVCpu, VMCPU_FF_DBGF))
432	{
433	if ( pVCpu->dbgf.s.cEvents > 0
434	&& pVCpu->dbgf.s.aEvents[pVCpu->dbgf.s.cEvents - 1].enmState == DBGFEVENTSTATE_CURRENT)
435	{
436	VBOXSTRICTRC rcStrict2 = DBGFR3EventHandlePending(pVM, pVCpu);
437	if ( rcStrict2 != VINF_SUCCESS
438	&& ( rcStrict == VINF_SUCCESS
439	\|\| RT_FAILURE(rcStrict2)
440	\|\| rcStrict2 < rcStrict) ) /** @todo oversimplified? */
441	rcStrict = rcStrict2;
442	}
443	}
444
445	return VBOXSTRICTRC_TODO(rcStrict);
446	}
447
448
449	/**
450	* Flag whether the event implies that we're stopped in the hypervisor code
451	* and have to block certain operations.
452	*
453	* @param pVM The cross context VM structure.
454	* @param enmEvent The event.
455	*/
456	static void dbgfR3EventSetStoppedInHyperFlag(PVM pVM, DBGFEVENTTYPE enmEvent)
457	{
458	switch (enmEvent)
459	{
460	case DBGFEVENT_STEPPED_HYPER:
461	case DBGFEVENT_ASSERTION_HYPER:
462	case DBGFEVENT_BREAKPOINT_HYPER:
463	pVM->dbgf.s.fStoppedInHyper = true;
464	break;
465	default:
466	pVM->dbgf.s.fStoppedInHyper = false;
467	break;
468	}
469	}
470
471
472	/**
473	* Try to determine the event context.
474	*
475	* @returns debug event context.
476	* @param pVM The cross context VM structure.
477	*/
478	static DBGFEVENTCTX dbgfR3FigureEventCtx(PVM pVM)
479	{
480	/** @todo SMP support! */
481	PVMCPU pVCpu = &pVM->aCpus[0];
482
483	switch (EMGetState(pVCpu))
484	{
485	case EMSTATE_RAW:
486	case EMSTATE_DEBUG_GUEST_RAW:
487	return DBGFEVENTCTX_RAW;
488
489	case EMSTATE_REM:
490	case EMSTATE_DEBUG_GUEST_REM:
491	return DBGFEVENTCTX_REM;
492
493	case EMSTATE_DEBUG_HYPER:
494	case EMSTATE_GURU_MEDITATION:
495	return DBGFEVENTCTX_HYPER;
496
497	default:
498	return DBGFEVENTCTX_OTHER;
499	}
500	}
501
502	/**
503	* The common event prologue code.
504	* It will set the 'stopped-in-hyper' flag, make sure someone is attached,
505	* and perhaps process any high priority pending actions (none yet).
506	*
507	* @returns VBox status code.
508	* @param pVM The cross context VM structure.
509	* @param enmEvent The event to be sent.
510	*/
511	static int dbgfR3EventPrologue(PVM pVM, DBGFEVENTTYPE enmEvent)
512	{
513	/** @todo SMP */
514	PVMCPU pVCpu = VMMGetCpu(pVM);
515
516	/*
517	* Check if a debugger is attached.
518	*/
519	if ( !pVM->dbgf.s.fAttached
520	&& !dbgfR3WaitForAttach(pVM, pVCpu, enmEvent))
521	{
522	Log(("DBGFR3VMMEventSrc: enmEvent=%d - debugger not attached\n", enmEvent));
523	return VERR_DBGF_NOT_ATTACHED;
524	}
525
526	/*
527	* Sync back the state from the REM.
528	*/
529	dbgfR3EventSetStoppedInHyperFlag(pVM, enmEvent);
530	#ifdef VBOX_WITH_REM
531	if (!pVM->dbgf.s.fStoppedInHyper)
532	REMR3StateUpdate(pVM, pVCpu);
533	#endif
534
535	/*
536	* Look thru pending commands and finish those which make sense now.
537	*/
538	/** @todo Process/purge pending commands. */
539	//int rc = DBGFR3VMMForcedAction(pVM);
540	return VINF_SUCCESS;
541	}
542
543
544	/**
545	* Sends the event in the event buffer.
546	*
547	* @returns VBox status code.
548	* @param pVM The cross context VM structure.
549	*/
550	static int dbgfR3SendEvent(PVM pVM)
551	{
552	int rc = RTSemPing(&pVM->dbgf.s.PingPong);
553	if (RT_SUCCESS(rc))
554	rc = dbgfR3VMMWait(pVM);
555
556	pVM->dbgf.s.fStoppedInHyper = false;
557	/** @todo sync VMM -> REM after exitting the debugger. everything may change while in the debugger! */
558	return rc;
559	}
560
561
562	/**
563	* Processes a pending event on the current CPU.
564	*
565	* This is called by EM in response to VINF_EM_DBG_EVENT.
566	*
567	* @returns Strict VBox status code.
568	* @param pVM The cross context VM structure.
569	* @param pVCpu The cross context per CPU structure.
570	*
571	* @thread EMT(pVCpu)
572	*/
573	VMMR3_INT_DECL(VBOXSTRICTRC) DBGFR3EventHandlePending(PVM pVM, PVMCPU pVCpu)
574	{
575	VMCPU_ASSERT_EMT(pVCpu);
576	VMCPU_FF_CLEAR(pVCpu, VMCPU_FF_DBGF);
577
578	/*
579	* Check that we've got an event first.
580	*/
581	AssertReturn(pVCpu->dbgf.s.cEvents > 0, VINF_SUCCESS);
582	AssertReturn(pVCpu->dbgf.s.aEvents[pVCpu->dbgf.s.cEvents - 1].enmState == DBGFEVENTSTATE_CURRENT, VINF_SUCCESS);
583	PDBGFEVENT pEvent = &pVCpu->dbgf.s.aEvents[pVCpu->dbgf.s.cEvents - 1].Event;
584
585	/*
586	* Make sure we've got a debugger and is allowed to speak to it.
587	*/
588	int rc = dbgfR3EventPrologue(pVM, pEvent->enmType);
589	if (RT_FAILURE(rc))
590	{
591	/** @todo drop them events? */
592	return rc;
593	}
594
595	/** @todo SMP + debugger speaker logic */
596	/*
597	* Copy the event over and mark it as ignore.
598	*/
599	pVM->dbgf.s.DbgEvent = *pEvent;
600	pVCpu->dbgf.s.aEvents[pVCpu->dbgf.s.cEvents - 1].enmState = DBGFEVENTSTATE_IGNORE;
601	return dbgfR3SendEvent(pVM);
602	}
603
604
605	/**
606	* Send a generic debugger event which takes no data.
607	*
608	* @returns VBox status code.
609	* @param pVM The cross context VM structure.
610	* @param enmEvent The event to send.
611	* @internal
612	*/
613	VMMR3DECL(int) DBGFR3Event(PVM pVM, DBGFEVENTTYPE enmEvent)
614	{
615	int rc = dbgfR3EventPrologue(pVM, enmEvent);
616	if (RT_FAILURE(rc))
617	return rc;
618
619	/*
620	* Send the event and process the reply communication.
621	*/
622	pVM->dbgf.s.DbgEvent.enmType = enmEvent;
623	pVM->dbgf.s.DbgEvent.enmCtx = dbgfR3FigureEventCtx(pVM);
624	return dbgfR3SendEvent(pVM);
625	}
626
627
628	/**
629	* Send a debugger event which takes the full source file location.
630	*
631	* @returns VBox status code.
632	* @param pVM The cross context VM structure.
633	* @param enmEvent The event to send.
634	* @param pszFile Source file.
635	* @param uLine Line number in source file.
636	* @param pszFunction Function name.
637	* @param pszFormat Message which accompanies the event.
638	* @param ... Message arguments.
639	* @internal
640	*/
641	VMMR3DECL(int) DBGFR3EventSrc(PVM pVM, DBGFEVENTTYPE enmEvent, const char pszFile, unsigned uLine, const char pszFunction, const char *pszFormat, ...)
642	{
643	va_list args;
644	va_start(args, pszFormat);
645	int rc = DBGFR3EventSrcV(pVM, enmEvent, pszFile, uLine, pszFunction, pszFormat, args);
646	va_end(args);
647	return rc;
648	}
649
650
651	/**
652	* Send a debugger event which takes the full source file location.
653	*
654	* @returns VBox status code.
655	* @param pVM The cross context VM structure.
656	* @param enmEvent The event to send.
657	* @param pszFile Source file.
658	* @param uLine Line number in source file.
659	* @param pszFunction Function name.
660	* @param pszFormat Message which accompanies the event.
661	* @param args Message arguments.
662	* @internal
663	*/
664	VMMR3DECL(int) DBGFR3EventSrcV(PVM pVM, DBGFEVENTTYPE enmEvent, const char pszFile, unsigned uLine, const char pszFunction, const char *pszFormat, va_list args)
665	{
666	int rc = dbgfR3EventPrologue(pVM, enmEvent);
667	if (RT_FAILURE(rc))
668	return rc;
669
670	/*
671	* Format the message.
672	*/
673	char *pszMessage = NULL;
674	char szMessage[8192];
675	if (pszFormat && *pszFormat)
676	{
677	pszMessage = &szMessage[0];
678	RTStrPrintfV(szMessage, sizeof(szMessage), pszFormat, args);
679	}
680
681	/*
682	* Send the event and process the reply communication.
683	*/
684	pVM->dbgf.s.DbgEvent.enmType = enmEvent;
685	pVM->dbgf.s.DbgEvent.enmCtx = dbgfR3FigureEventCtx(pVM);
686	pVM->dbgf.s.DbgEvent.u.Src.pszFile = pszFile;
687	pVM->dbgf.s.DbgEvent.u.Src.uLine = uLine;
688	pVM->dbgf.s.DbgEvent.u.Src.pszFunction = pszFunction;
689	pVM->dbgf.s.DbgEvent.u.Src.pszMessage = pszMessage;
690	return dbgfR3SendEvent(pVM);
691	}
692
693
694	/**
695	* Send a debugger event which takes the two assertion messages.
696	*
697	* @returns VBox status code.
698	* @param pVM The cross context VM structure.
699	* @param enmEvent The event to send.
700	* @param pszMsg1 First assertion message.
701	* @param pszMsg2 Second assertion message.
702	*/
703	VMMR3_INT_DECL(int) DBGFR3EventAssertion(PVM pVM, DBGFEVENTTYPE enmEvent, const char pszMsg1, const char pszMsg2)
704	{
705	int rc = dbgfR3EventPrologue(pVM, enmEvent);
706	if (RT_FAILURE(rc))
707	return rc;
708
709	/*
710	* Send the event and process the reply communication.
711	*/
712	pVM->dbgf.s.DbgEvent.enmType = enmEvent;
713	pVM->dbgf.s.DbgEvent.enmCtx = dbgfR3FigureEventCtx(pVM);
714	pVM->dbgf.s.DbgEvent.u.Assert.pszMsg1 = pszMsg1;
715	pVM->dbgf.s.DbgEvent.u.Assert.pszMsg2 = pszMsg2;
716	return dbgfR3SendEvent(pVM);
717	}
718
719
720	/**
721	* Breakpoint was hit somewhere.
722	* Figure out which breakpoint it is and notify the debugger.
723	*
724	* @returns VBox status code.
725	* @param pVM The cross context VM structure.
726	* @param enmEvent DBGFEVENT_BREAKPOINT_HYPER or DBGFEVENT_BREAKPOINT.
727	*/
728	VMMR3_INT_DECL(int) DBGFR3EventBreakpoint(PVM pVM, DBGFEVENTTYPE enmEvent)
729	{
730	int rc = dbgfR3EventPrologue(pVM, enmEvent);
731	if (RT_FAILURE(rc))
732	return rc;
733
734	/*
735	* Send the event and process the reply communication.
736	*/
737	/** @todo SMP */
738	PVMCPU pVCpu = VMMGetCpu0(pVM);
739
740	pVM->dbgf.s.DbgEvent.enmType = enmEvent;
741	RTUINT iBp = pVM->dbgf.s.DbgEvent.u.Bp.iBp = pVCpu->dbgf.s.iActiveBp;
742	pVCpu->dbgf.s.iActiveBp = ~0U;
743	if (iBp != ~0U)
744	pVM->dbgf.s.DbgEvent.enmCtx = DBGFEVENTCTX_RAW;
745	else
746	{
747	/* REM breakpoints has be been searched for. */
748	#if 0 /** @todo get flat PC api! */
749	uint32_t eip = CPUMGetGuestEIP(pVM);
750	#else
751	/* @todo SMP support!! */
752	PCPUMCTX pCtx = CPUMQueryGuestCtxPtr(VMMGetCpu(pVM));
753	RTGCPTR eip = pCtx->rip + pCtx->cs.u64Base;
754	#endif
755	for (size_t i = 0; i < RT_ELEMENTS(pVM->dbgf.s.aBreakpoints); i++)
756	if ( pVM->dbgf.s.aBreakpoints[i].enmType == DBGFBPTYPE_REM
757	&& pVM->dbgf.s.aBreakpoints[i].u.Rem.GCPtr == eip)
758	{
759	pVM->dbgf.s.DbgEvent.u.Bp.iBp = pVM->dbgf.s.aBreakpoints[i].iBp;
760	break;
761	}
762	AssertMsg(pVM->dbgf.s.DbgEvent.u.Bp.iBp != ~0U, ("eip=%08x\n", eip));
763	pVM->dbgf.s.DbgEvent.enmCtx = DBGFEVENTCTX_REM;
764	}
765	return dbgfR3SendEvent(pVM);
766	}
767
768
769	/**
770	* Waits for the debugger to respond.
771	*
772	* @returns VBox status code. (clearify)
773	* @param pVM The cross context VM structure.
774	*/
775	static int dbgfR3VMMWait(PVM pVM)
776	{
777	PVMCPU pVCpu = VMMGetCpu(pVM);
778
779	LogFlow(("dbgfR3VMMWait:\n"));
780	int rcRet = VINF_SUCCESS;
781
782	/*
783	* Waits for the debugger to reply (i.e. issue an command).
784	*/
785	for (;;)
786	{
787	/*
788	* Wait.
789	*/
790	uint32_t cPollHack = 1; /** @todo this interface is horrible now that we're using lots of VMR3ReqCall stuff all over DBGF. */
791	for (;;)
792	{
793	int rc;
794	if ( !VM_FF_IS_PENDING(pVM, VM_FF_EMT_RENDEZVOUS \| VM_FF_REQUEST)
795	&& !VMCPU_FF_IS_PENDING(pVCpu, VMCPU_FF_REQUEST))
796	{
797	rc = RTSemPingWait(&pVM->dbgf.s.PingPong, cPollHack);
798	if (RT_SUCCESS(rc))
799	break;
800	if (rc != VERR_TIMEOUT)
801	{
802	LogFlow(("dbgfR3VMMWait: returns %Rrc\n", rc));
803	return rc;
804	}
805	}
806
807	if (VM_FF_IS_PENDING(pVM, VM_FF_EMT_RENDEZVOUS))
808	{
809	rc = VMMR3EmtRendezvousFF(pVM, pVCpu);
810	cPollHack = 1;
811	}
812	else if ( VM_FF_IS_PENDING(pVM, VM_FF_REQUEST)
813	\|\| VMCPU_FF_IS_PENDING(pVCpu, VMCPU_FF_REQUEST))
814	{
815	LogFlow(("dbgfR3VMMWait: Processes requests...\n"));
816	rc = VMR3ReqProcessU(pVM->pUVM, VMCPUID_ANY, false /fPriorityOnly/);
817	if (rc == VINF_SUCCESS)
818	rc = VMR3ReqProcessU(pVM->pUVM, pVCpu->idCpu, false /fPriorityOnly/);
819	LogFlow(("dbgfR3VMMWait: VMR3ReqProcess -> %Rrc rcRet=%Rrc\n", rc, rcRet));
820	cPollHack = 1;
821	}
822	else
823	{
824	rc = VINF_SUCCESS;
825	if (cPollHack < 120)
826	cPollHack++;
827	}
828
829	if (rc >= VINF_EM_FIRST && rc <= VINF_EM_LAST)
830	{
831	switch (rc)
832	{
833	case VINF_EM_DBG_BREAKPOINT:
834	case VINF_EM_DBG_STEPPED:
835	case VINF_EM_DBG_STEP:
836	case VINF_EM_DBG_STOP:
837	case VINF_EM_DBG_EVENT:
838	AssertMsgFailed(("rc=%Rrc\n", rc));
839	break;
840
841	/* return straight away */
842	case VINF_EM_TERMINATE:
843	case VINF_EM_OFF:
844	LogFlow(("dbgfR3VMMWait: returns %Rrc\n", rc));
845	return rc;
846
847	/* remember return code. */
848	default:
849	AssertReleaseMsgFailed(("rc=%Rrc is not in the switch!\n", rc));
850	case VINF_EM_RESET:
851	case VINF_EM_SUSPEND:
852	case VINF_EM_HALT:
853	case VINF_EM_RESUME:
854	case VINF_EM_RESCHEDULE:
855	case VINF_EM_RESCHEDULE_REM:
856	case VINF_EM_RESCHEDULE_RAW:
857	if (rc < rcRet \|\| rcRet == VINF_SUCCESS)
858	rcRet = rc;
859	break;
860	}
861	}
862	else if (RT_FAILURE(rc))
863	{
864	LogFlow(("dbgfR3VMMWait: returns %Rrc\n", rc));
865	return rc;
866	}
867	}
868
869	/*
870	* Process the command.
871	*/
872	bool fResumeExecution;
873	DBGFCMDDATA CmdData = pVM->dbgf.s.VMMCmdData;
874	DBGFCMD enmCmd = dbgfR3SetCmd(pVM, DBGFCMD_NO_COMMAND);
875	int rc = dbgfR3VMMCmd(pVM, enmCmd, &CmdData, &fResumeExecution);
876	if (fResumeExecution)
877	{
878	if (RT_FAILURE(rc))
879	rcRet = rc;
880	else if ( rc >= VINF_EM_FIRST
881	&& rc <= VINF_EM_LAST
882	&& (rc < rcRet \|\| rcRet == VINF_SUCCESS))
883	rcRet = rc;
884	LogFlow(("dbgfR3VMMWait: returns %Rrc\n", rcRet));
885	return rcRet;
886	}
887	}
888	}
889
890
891	/**
892	* Executes command from debugger.
893	* The caller is responsible for waiting or resuming execution based on the
894	* value returned in the *pfResumeExecution indicator.
895	*
896	* @returns VBox status code. (clearify!)
897	* @param pVM The cross context VM structure.
898	* @param enmCmd The command in question.
899	* @param pCmdData Pointer to the command data.
900	* @param pfResumeExecution Where to store the resume execution / continue waiting indicator.
901	*/
902	static int dbgfR3VMMCmd(PVM pVM, DBGFCMD enmCmd, PDBGFCMDDATA pCmdData, bool *pfResumeExecution)
903	{
904	bool fSendEvent;
905	bool fResume;
906	int rc = VINF_SUCCESS;
907
908	NOREF(pCmdData); /* for later */
909
910	switch (enmCmd)
911	{
912	/*
913	* Halt is answered by an event say that we've halted.
914	*/
915	case DBGFCMD_HALT:
916	{
917	pVM->dbgf.s.DbgEvent.enmType = DBGFEVENT_HALT_DONE;
918	pVM->dbgf.s.DbgEvent.enmCtx = dbgfR3FigureEventCtx(pVM);
919	fSendEvent = true;
920	fResume = false;
921	break;
922	}
923
924
925	/*
926	* Resume is not answered we'll just resume execution.
927	*/
928	case DBGFCMD_GO:
929	{
930	/** @todo SMP */
931	PVMCPU pVCpu = VMMGetCpu0(pVM);
932	pVCpu->dbgf.s.fSingleSteppingRaw = false;
933	fSendEvent = false;
934	fResume = true;
935	break;
936	}
937
938	/** @todo implement (and define) the rest of the commands. */
939
940	/*
941	* Disable breakpoints and stuff.
942	* Send an everythings cool event to the debugger thread and resume execution.
943	*/
944	case DBGFCMD_DETACH_DEBUGGER:
945	{
946	ASMAtomicWriteBool(&pVM->dbgf.s.fAttached, false);
947	pVM->dbgf.s.DbgEvent.enmType = DBGFEVENT_DETACH_DONE;
948	pVM->dbgf.s.DbgEvent.enmCtx = DBGFEVENTCTX_OTHER;
949	fSendEvent = true;
950	fResume = true;
951	break;
952	}
953
954	/*
955	* The debugger has detached successfully.
956	* There is no reply to this event.
957	*/
958	case DBGFCMD_DETACHED_DEBUGGER:
959	{
960	fSendEvent = false;
961	fResume = true;
962	break;
963	}
964
965	/*
966	* Single step, with trace into.
967	*/
968	case DBGFCMD_SINGLE_STEP:
969	{
970	Log2(("Single step\n"));
971	rc = VINF_EM_DBG_STEP;
972	/** @todo SMP */
973	PVMCPU pVCpu = VMMGetCpu0(pVM);
974	pVCpu->dbgf.s.fSingleSteppingRaw = true;
975	fSendEvent = false;
976	fResume = true;
977	break;
978	}
979
980	/*
981	* Default is to send an invalid command event.
982	*/
983	default:
984	{
985	pVM->dbgf.s.DbgEvent.enmType = DBGFEVENT_INVALID_COMMAND;
986	pVM->dbgf.s.DbgEvent.enmCtx = dbgfR3FigureEventCtx(pVM);
987	fSendEvent = true;
988	fResume = false;
989	break;
990	}
991	}
992
993	/*
994	* Send pending event.
995	*/
996	if (fSendEvent)
997	{
998	Log2(("DBGF: Emulation thread: sending event %d\n", pVM->dbgf.s.DbgEvent.enmType));
999	int rc2 = RTSemPing(&pVM->dbgf.s.PingPong);
1000	if (RT_FAILURE(rc2))
1001	{
1002	AssertRC(rc2);
1003	*pfResumeExecution = true;
1004	return rc2;
1005	}
1006	}
1007
1008	/*
1009	* Return.
1010	*/
1011	*pfResumeExecution = fResume;
1012	return rc;
1013	}
1014
1015
1016	/**
1017	* Attaches a debugger to the specified VM.
1018	*
1019	* Only one debugger at a time.
1020	*
1021	* @returns VBox status code.
1022	* @param pUVM The user mode VM handle.
1023	*/
1024	VMMR3DECL(int) DBGFR3Attach(PUVM pUVM)
1025	{
1026	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1027	PVM pVM = pUVM->pVM;
1028	VM_ASSERT_VALID_EXT_RETURN(pVM, VERR_INVALID_VM_HANDLE);
1029
1030	/*
1031	* Call the VM, use EMT for serialization.
1032	*
1033	* Using a priority call here so we can actually attach a debugger during
1034	* the countdown in dbgfR3WaitForAttach.
1035	*/
1036	/** @todo SMP */
1037	return VMR3ReqPriorityCallWait(pVM, VMCPUID_ANY, (PFNRT)dbgfR3Attach, 1, pVM);
1038	}
1039
1040
1041	/**
1042	* EMT worker for DBGFR3Attach.
1043	*
1044	* @returns VBox status code.
1045	* @param pVM The cross context VM structure.
1046	*/
1047	static DECLCALLBACK(int) dbgfR3Attach(PVM pVM)
1048	{
1049	if (pVM->dbgf.s.fAttached)
1050	{
1051	Log(("dbgR3Attach: Debugger already attached\n"));
1052	return VERR_DBGF_ALREADY_ATTACHED;
1053	}
1054
1055	/*
1056	* Create the Ping-Pong structure.
1057	*/
1058	int rc = RTSemPingPongInit(&pVM->dbgf.s.PingPong);
1059	AssertRCReturn(rc, rc);
1060
1061	/*
1062	* Set the attached flag.
1063	*/
1064	ASMAtomicWriteBool(&pVM->dbgf.s.fAttached, true);
1065	return VINF_SUCCESS;
1066	}
1067
1068
1069	/**
1070	* Detaches a debugger from the specified VM.
1071	*
1072	* Caller must be attached to the VM.
1073	*
1074	* @returns VBox status code.
1075	* @param pUVM The user mode VM handle.
1076	*/
1077	VMMR3DECL(int) DBGFR3Detach(PUVM pUVM)
1078	{
1079	LogFlow(("DBGFR3Detach:\n"));
1080	int rc;
1081
1082	/*
1083	* Validate input. The UVM handle shall be valid, the VM handle might be
1084	* in the processes of being destroyed already, so deal quietly with that.
1085	*/
1086	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1087	PVM pVM = pUVM->pVM;
1088	if (!VM_IS_VALID_EXT(pVM))
1089	return VERR_INVALID_VM_HANDLE;
1090
1091	/*
1092	* Check if attached.
1093	*/
1094	if (!pVM->dbgf.s.fAttached)
1095	return VERR_DBGF_NOT_ATTACHED;
1096
1097	/*
1098	* Try send the detach command.
1099	* Keep in mind that we might be racing EMT, so, be extra careful.
1100	*/
1101	DBGFCMD enmCmd = dbgfR3SetCmd(pVM, DBGFCMD_DETACH_DEBUGGER);
1102	if (RTSemPongIsSpeaker(&pVM->dbgf.s.PingPong))
1103	{
1104	rc = RTSemPong(&pVM->dbgf.s.PingPong);
1105	AssertMsgRCReturn(rc, ("Failed to signal emulation thread. rc=%Rrc\n", rc), rc);
1106	LogRel(("DBGFR3Detach: enmCmd=%d (pong -> ping)\n", enmCmd));
1107	}
1108
1109	/*
1110	* Wait for the OK event.
1111	*/
1112	rc = RTSemPongWait(&pVM->dbgf.s.PingPong, RT_INDEFINITE_WAIT);
1113	AssertLogRelMsgRCReturn(rc, ("Wait on detach command failed, rc=%Rrc\n", rc), rc);
1114
1115	/*
1116	* Send the notification command indicating that we're really done.
1117	*/
1118	enmCmd = dbgfR3SetCmd(pVM, DBGFCMD_DETACHED_DEBUGGER);
1119	rc = RTSemPong(&pVM->dbgf.s.PingPong);
1120	AssertMsgRCReturn(rc, ("Failed to signal emulation thread. rc=%Rrc\n", rc), rc);
1121
1122	LogFlowFunc(("returns VINF_SUCCESS\n"));
1123	return VINF_SUCCESS;
1124	}
1125
1126
1127	/**
1128	* Wait for a debug event.
1129	*
1130	* @returns VBox status code. Will not return VBOX_INTERRUPTED.
1131	* @param pUVM The user mode VM handle.
1132	* @param cMillies Number of millis to wait.
1133	* @param ppEvent Where to store the event pointer.
1134	*/
1135	VMMR3DECL(int) DBGFR3EventWait(PUVM pUVM, RTMSINTERVAL cMillies, PCDBGFEVENT *ppEvent)
1136	{
1137	/*
1138	* Check state.
1139	*/
1140	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1141	PVM pVM = pUVM->pVM;
1142	VM_ASSERT_VALID_EXT_RETURN(pVM, VERR_INVALID_VM_HANDLE);
1143	AssertReturn(pVM->dbgf.s.fAttached, VERR_DBGF_NOT_ATTACHED);
1144	*ppEvent = NULL;
1145
1146	/*
1147	* Wait.
1148	*/
1149	int rc = RTSemPongWait(&pVM->dbgf.s.PingPong, cMillies);
1150	if (RT_SUCCESS(rc))
1151	{
1152	*ppEvent = &pVM->dbgf.s.DbgEvent;
1153	Log2(("DBGF: Debugger thread: receiving event %d\n", (*ppEvent)->enmType));
1154	return VINF_SUCCESS;
1155	}
1156
1157	return rc;
1158	}
1159
1160
1161	/**
1162	* Halts VM execution.
1163	*
1164	* After calling this the VM isn't actually halted till an DBGFEVENT_HALT_DONE
1165	* arrives. Until that time it's not possible to issue any new commands.
1166	*
1167	* @returns VBox status code.
1168	* @param pUVM The user mode VM handle.
1169	*/
1170	VMMR3DECL(int) DBGFR3Halt(PUVM pUVM)
1171	{
1172	/*
1173	* Check state.
1174	*/
1175	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1176	PVM pVM = pUVM->pVM;
1177	VM_ASSERT_VALID_EXT_RETURN(pVM, VERR_INVALID_VM_HANDLE);
1178	AssertReturn(pVM->dbgf.s.fAttached, VERR_DBGF_NOT_ATTACHED);
1179	RTPINGPONGSPEAKER enmSpeaker = pVM->dbgf.s.PingPong.enmSpeaker;
1180	if ( enmSpeaker == RTPINGPONGSPEAKER_PONG
1181	\|\| enmSpeaker == RTPINGPONGSPEAKER_PONG_SIGNALED)
1182	return VWRN_DBGF_ALREADY_HALTED;
1183
1184	/*
1185	* Send command.
1186	*/
1187	dbgfR3SetCmd(pVM, DBGFCMD_HALT);
1188
1189	return VINF_SUCCESS;
1190	}
1191
1192
1193	/**
1194	* Checks if the VM is halted by the debugger.
1195	*
1196	* @returns True if halted.
1197	* @returns False if not halted.
1198	* @param pUVM The user mode VM handle.
1199	*/
1200	VMMR3DECL(bool) DBGFR3IsHalted(PUVM pUVM)
1201	{
1202	UVM_ASSERT_VALID_EXT_RETURN(pUVM, false);
1203	PVM pVM = pUVM->pVM;
1204	VM_ASSERT_VALID_EXT_RETURN(pVM, false);
1205	AssertReturn(pVM->dbgf.s.fAttached, false);
1206
1207	RTPINGPONGSPEAKER enmSpeaker = pVM->dbgf.s.PingPong.enmSpeaker;
1208	return enmSpeaker == RTPINGPONGSPEAKER_PONG_SIGNALED
1209	\|\| enmSpeaker == RTPINGPONGSPEAKER_PONG;
1210	}
1211
1212
1213	/**
1214	* Checks if the debugger can wait for events or not.
1215	*
1216	* This function is only used by lazy, multiplexing debuggers. :-)
1217	*
1218	* @returns VBox status code.
1219	* @retval VINF_SUCCESS if waitable.
1220	* @retval VERR_SEM_OUT_OF_TURN if not waitable.
1221	* @retval VERR_INVALID_VM_HANDLE if the VM is being (/ has been) destroyed
1222	* (not asserted) or if the handle is invalid (asserted).
1223	* @retval VERR_DBGF_NOT_ATTACHED if not attached.
1224	*
1225	* @param pUVM The user mode VM handle.
1226	*/
1227	VMMR3DECL(int) DBGFR3QueryWaitable(PUVM pUVM)
1228	{
1229	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1230
1231	/* Note! There is a slight race here, unfortunately. */
1232	PVM pVM = pUVM->pVM;
1233	if (!RT_VALID_PTR(pVM))
1234	return VERR_INVALID_VM_HANDLE;
1235	if (pVM->enmVMState >= VMSTATE_DESTROYING)
1236	return VERR_INVALID_VM_HANDLE;
1237	if (!pVM->dbgf.s.fAttached)
1238	return VERR_DBGF_NOT_ATTACHED;
1239
1240	if (!RTSemPongShouldWait(&pVM->dbgf.s.PingPong))
1241	return VERR_SEM_OUT_OF_TURN;
1242
1243	return VINF_SUCCESS;
1244	}
1245
1246
1247	/**
1248	* Resumes VM execution.
1249	*
1250	* There is no receipt event on this command.
1251	*
1252	* @returns VBox status code.
1253	* @param pUVM The user mode VM handle.
1254	*/
1255	VMMR3DECL(int) DBGFR3Resume(PUVM pUVM)
1256	{
1257	/*
1258	* Check state.
1259	*/
1260	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1261	PVM pVM = pUVM->pVM;
1262	VM_ASSERT_VALID_EXT_RETURN(pVM, VERR_INVALID_VM_HANDLE);
1263	AssertReturn(pVM->dbgf.s.fAttached, VERR_DBGF_NOT_ATTACHED);
1264	if (RT_LIKELY(RTSemPongIsSpeaker(&pVM->dbgf.s.PingPong)))
1265	{ /* likely */ }
1266	else
1267	return VERR_SEM_OUT_OF_TURN;
1268
1269	/*
1270	* Send the ping back to the emulation thread telling it to run.
1271	*/
1272	dbgfR3SetCmd(pVM, DBGFCMD_GO);
1273	int rc = RTSemPong(&pVM->dbgf.s.PingPong);
1274	AssertRC(rc);
1275
1276	return rc;
1277	}
1278
1279
1280	/**
1281	* Step Into.
1282	*
1283	* A single step event is generated from this command.
1284	* The current implementation is not reliable, so don't rely on the event coming.
1285	*
1286	* @returns VBox status code.
1287	* @param pUVM The user mode VM handle.
1288	* @param idCpu The ID of the CPU to single step on.
1289	*/
1290	VMMR3DECL(int) DBGFR3Step(PUVM pUVM, VMCPUID idCpu)
1291	{
1292	/*
1293	* Check state.
1294	*/
1295	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1296	PVM pVM = pUVM->pVM;
1297	VM_ASSERT_VALID_EXT_RETURN(pVM, VERR_INVALID_VM_HANDLE);
1298	AssertReturn(idCpu < pVM->cCpus, VERR_INVALID_PARAMETER);
1299	AssertReturn(pVM->dbgf.s.fAttached, VERR_DBGF_NOT_ATTACHED);
1300	if (RT_LIKELY(RTSemPongIsSpeaker(&pVM->dbgf.s.PingPong)))
1301	{ /* likely */ }
1302	else
1303	return VERR_SEM_OUT_OF_TURN;
1304
1305	/*
1306	* Send the ping back to the emulation thread telling it to run.
1307	*/
1308	/** @todo SMP (idCpu) */
1309	dbgfR3SetCmd(pVM, DBGFCMD_SINGLE_STEP);
1310	int rc = RTSemPong(&pVM->dbgf.s.PingPong);
1311	AssertRC(rc);
1312	return rc;
1313	}
1314
1315
1316
1317	/**
1318	* dbgfR3EventConfigEx argument packet.
1319	*/
1320	typedef struct DBGFR3EVENTCONFIGEXARGS
1321	{
1322	PCDBGFEVENTCONFIG paConfigs;
1323	size_t cConfigs;
1324	int rc;
1325	} DBGFR3EVENTCONFIGEXARGS;
1326	/** Pointer to a dbgfR3EventConfigEx argument packet. */
1327	typedef DBGFR3EVENTCONFIGEXARGS *PDBGFR3EVENTCONFIGEXARGS;
1328
1329
1330	/**
1331	* @callback_method_impl{FNVMMEMTRENDEZVOUS, Worker for DBGFR3EventConfigEx.}
1332	*/
1333	static DECLCALLBACK(VBOXSTRICTRC) dbgfR3EventConfigEx(PVM pVM, PVMCPU pVCpu, void *pvUser)
1334	{
1335	if (pVCpu->idCpu == 0)
1336	{
1337	PDBGFR3EVENTCONFIGEXARGS pArgs = (PDBGFR3EVENTCONFIGEXARGS)pvUser;
1338	DBGFEVENTCONFIG volatile const *paConfigs = pArgs->paConfigs;
1339	size_t cConfigs = pArgs->cConfigs;
1340
1341	/*
1342	* Apply the changes.
1343	*/
1344	unsigned cChanges = 0;
1345	for (uint32_t i = 0; i < cConfigs; i++)
1346	{
1347	DBGFEVENTTYPE enmType = paConfigs[i].enmType;
1348	AssertReturn(enmType >= DBGFEVENT_FIRST_SELECTABLE && enmType < DBGFEVENT_END, VERR_INVALID_PARAMETER);
1349	if (paConfigs[i].fEnabled)
1350	cChanges += ASMAtomicBitTestAndSet(&pVM->dbgf.s.bmSelectedEvents, enmType) == false;
1351	else
1352	cChanges += ASMAtomicBitTestAndClear(&pVM->dbgf.s.bmSelectedEvents, enmType) == true;
1353	}
1354
1355	/*
1356	* Inform HM about changes.
1357	*/
1358	if (cChanges > 0 && HMIsEnabled(pVM))
1359	{
1360	HMR3NotifyDebugEventChanged(pVM);
1361	HMR3NotifyDebugEventChangedPerCpu(pVM, pVCpu);
1362	}
1363	}
1364	else if (HMIsEnabled(pVM))
1365	HMR3NotifyDebugEventChangedPerCpu(pVM, pVCpu);
1366
1367	return VINF_SUCCESS;
1368	}
1369
1370
1371	/**
1372	* Configures (enables/disables) multiple selectable debug events.
1373	*
1374	* @returns VBox status code.
1375	* @param pUVM The user mode VM handle.
1376	* @param paConfigs The event to configure and their new state.
1377	* @param cConfigs Number of entries in @a paConfigs.
1378	*/
1379	VMMR3DECL(int) DBGFR3EventConfigEx(PUVM pUVM, PCDBGFEVENTCONFIG paConfigs, size_t cConfigs)
1380	{
1381	/*
1382	* Validate input.
1383	*/
1384	size_t i = cConfigs;
1385	while (i-- > 0)
1386	{
1387	AssertReturn(paConfigs[i].enmType >= DBGFEVENT_FIRST_SELECTABLE, VERR_INVALID_PARAMETER);
1388	AssertReturn(paConfigs[i].enmType < DBGFEVENT_END, VERR_INVALID_PARAMETER);
1389	}
1390	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1391	PVM pVM = pUVM->pVM;
1392	VM_ASSERT_VALID_EXT_RETURN(pVM, VERR_INVALID_VM_HANDLE);
1393
1394	/*
1395	* Apply the changes in EMT(0) and rendezvous with the other CPUs so they
1396	* can sync their data and execution with new debug state.
1397	*/
1398	DBGFR3EVENTCONFIGEXARGS Args = { paConfigs, cConfigs, VINF_SUCCESS };
1399	int rc = VMMR3EmtRendezvous(pVM, VMMEMTRENDEZVOUS_FLAGS_TYPE_ASCENDING \| VMMEMTRENDEZVOUS_FLAGS_PRIORITY,
1400	dbgfR3EventConfigEx, &Args);
1401	if (RT_SUCCESS(rc))
1402	rc = Args.rc;
1403	return rc;
1404	}
1405
1406
1407	/**
1408	* Enables or disables a selectable debug event.
1409	*
1410	* @returns VBox status code.
1411	* @param pUVM The user mode VM handle.
1412	* @param enmEvent The selectable debug event.
1413	* @param fEnabled The new state.
1414	*/
1415	VMMR3DECL(int) DBGFR3EventConfig(PUVM pUVM, DBGFEVENTTYPE enmEvent, bool fEnabled)
1416	{
1417	/*
1418	* Convert to an array call.
1419	*/
1420	DBGFEVENTCONFIG EvtCfg = { enmEvent, fEnabled };
1421	return DBGFR3EventConfigEx(pUVM, &EvtCfg, 1);
1422	}
1423
1424
1425	/**
1426	* Checks if the given selectable event is enabled.
1427	*
1428	* @returns true if enabled, false if not or invalid input.
1429	* @param pUVM The user mode VM handle.
1430	* @param enmEvent The selectable debug event.
1431	* @sa DBGFR3EventQuery
1432	*/
1433	VMMR3DECL(bool) DBGFR3EventIsEnabled(PUVM pUVM, DBGFEVENTTYPE enmEvent)
1434	{
1435	/*
1436	* Validate input.
1437	*/
1438	AssertReturn( enmEvent >= DBGFEVENT_HALT_DONE
1439	&& enmEvent < DBGFEVENT_END, false);
1440	Assert( enmEvent >= DBGFEVENT_FIRST_SELECTABLE
1441	\|\| enmEvent == DBGFEVENT_BREAKPOINT
1442	\|\| enmEvent == DBGFEVENT_BREAKPOINT_IO
1443	\|\| enmEvent == DBGFEVENT_BREAKPOINT_MMIO);
1444
1445	UVM_ASSERT_VALID_EXT_RETURN(pUVM, false);
1446	PVM pVM = pUVM->pVM;
1447	VM_ASSERT_VALID_EXT_RETURN(pVM, false);
1448
1449	/*
1450	* Check the event status.
1451	*/
1452	return ASMBitTest(&pVM->dbgf.s.bmSelectedEvents, enmEvent);
1453	}
1454
1455
1456	/**
1457	* Queries the status of a set of events.
1458	*
1459	* @returns VBox status code.
1460	* @param pUVM The user mode VM handle.
1461	* @param paConfigs The events to query and where to return the state.
1462	* @param cConfigs The number of elements in @a paConfigs.
1463	* @sa DBGFR3EventIsEnabled, DBGF_IS_EVENT_ENABLED
1464	*/
1465	VMMR3DECL(int) DBGFR3EventQuery(PUVM pUVM, PDBGFEVENTCONFIG paConfigs, size_t cConfigs)
1466	{
1467	/*
1468	* Validate input.
1469	*/
1470	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1471	PVM pVM = pUVM->pVM;
1472	VM_ASSERT_VALID_EXT_RETURN(pVM, VERR_INVALID_VM_HANDLE);
1473
1474	for (size_t i = 0; i < cConfigs; i++)
1475	{
1476	DBGFEVENTTYPE enmType = paConfigs[i].enmType;
1477	AssertReturn( enmType >= DBGFEVENT_HALT_DONE
1478	&& enmType < DBGFEVENT_END, VERR_INVALID_PARAMETER);
1479	Assert( enmType >= DBGFEVENT_FIRST_SELECTABLE
1480	\|\| enmType == DBGFEVENT_BREAKPOINT
1481	\|\| enmType == DBGFEVENT_BREAKPOINT_IO
1482	\|\| enmType == DBGFEVENT_BREAKPOINT_MMIO);
1483	paConfigs[i].fEnabled = ASMBitTest(&pVM->dbgf.s.bmSelectedEvents, paConfigs[i].enmType);
1484	}
1485
1486	return VINF_SUCCESS;
1487	}
1488
1489
1490	/**
1491	* dbgfR3InterruptConfigEx argument packet.
1492	*/
1493	typedef struct DBGFR3INTERRUPTCONFIGEXARGS
1494	{
1495	PCDBGFINTERRUPTCONFIG paConfigs;
1496	size_t cConfigs;
1497	int rc;
1498	} DBGFR3INTERRUPTCONFIGEXARGS;
1499	/** Pointer to a dbgfR3InterruptConfigEx argument packet. */
1500	typedef DBGFR3INTERRUPTCONFIGEXARGS *PDBGFR3INTERRUPTCONFIGEXARGS;
1501
1502	/**
1503	* @callback_method_impl{FNVMMEMTRENDEZVOUS,
1504	* Worker for DBGFR3InterruptConfigEx.}
1505	*/
1506	static DECLCALLBACK(VBOXSTRICTRC) dbgfR3InterruptConfigEx(PVM pVM, PVMCPU pVCpu, void *pvUser)
1507	{
1508	if (pVCpu->idCpu == 0)
1509	{
1510	PDBGFR3INTERRUPTCONFIGEXARGS pArgs = (PDBGFR3INTERRUPTCONFIGEXARGS)pvUser;
1511	PCDBGFINTERRUPTCONFIG paConfigs = pArgs->paConfigs;
1512	size_t cConfigs = pArgs->cConfigs;
1513
1514	/*
1515	* Apply the changes.
1516	*/
1517	bool fChanged = false;
1518	bool fThis;
1519	for (uint32_t i = 0; i < cConfigs; i++)
1520	{
1521	/*
1522	* Hardware interrupts.
1523	*/
1524	if (paConfigs[i].enmHardState == DBGFINTERRUPTSTATE_ENABLED)
1525	{
1526	fChanged \|= fThis = ASMAtomicBitTestAndSet(&pVM->dbgf.s.bmHardIntBreakpoints, paConfigs[i].iInterrupt) == false;
1527	if (fThis)
1528	{
1529	Assert(pVM->dbgf.s.cHardIntBreakpoints < 256);
1530	pVM->dbgf.s.cHardIntBreakpoints++;
1531	}
1532	}
1533	else if (paConfigs[i].enmHardState == DBGFINTERRUPTSTATE_DISABLED)
1534	{
1535	fChanged \|= fThis = ASMAtomicBitTestAndClear(&pVM->dbgf.s.bmHardIntBreakpoints, paConfigs[i].iInterrupt) == true;
1536	if (fThis)
1537	{
1538	Assert(pVM->dbgf.s.cHardIntBreakpoints > 0);
1539	pVM->dbgf.s.cHardIntBreakpoints--;
1540	}
1541	}
1542
1543	/*
1544	* Software interrupts.
1545	*/
1546	if (paConfigs[i].enmHardState == DBGFINTERRUPTSTATE_ENABLED)
1547	{
1548	fChanged \|= fThis = ASMAtomicBitTestAndSet(&pVM->dbgf.s.bmSoftIntBreakpoints, paConfigs[i].iInterrupt) == false;
1549	if (fThis)
1550	{
1551	Assert(pVM->dbgf.s.cSoftIntBreakpoints < 256);
1552	pVM->dbgf.s.cSoftIntBreakpoints++;
1553	}
1554	}
1555	else if (paConfigs[i].enmSoftState == DBGFINTERRUPTSTATE_DISABLED)
1556	{
1557	fChanged \|= fThis = ASMAtomicBitTestAndClear(&pVM->dbgf.s.bmSoftIntBreakpoints, paConfigs[i].iInterrupt) == true;
1558	if (fThis)
1559	{
1560	Assert(pVM->dbgf.s.cSoftIntBreakpoints > 0);
1561	pVM->dbgf.s.cSoftIntBreakpoints--;
1562	}
1563	}
1564	}
1565
1566	/*
1567	* Update the event bitmap entries.
1568	*/
1569	if (pVM->dbgf.s.cHardIntBreakpoints > 0)
1570	fChanged \|= ASMAtomicBitTestAndSet(&pVM->dbgf.s.bmSelectedEvents, DBGFEVENT_INTERRUPT_HARDWARE) == false;
1571	else
1572	fChanged \|= ASMAtomicBitTestAndClear(&pVM->dbgf.s.bmSelectedEvents, DBGFEVENT_INTERRUPT_HARDWARE) == true;
1573
1574	if (pVM->dbgf.s.cSoftIntBreakpoints > 0)
1575	fChanged \|= ASMAtomicBitTestAndSet(&pVM->dbgf.s.bmSelectedEvents, DBGFEVENT_INTERRUPT_SOFTWARE) == false;
1576	else
1577	fChanged \|= ASMAtomicBitTestAndClear(&pVM->dbgf.s.bmSelectedEvents, DBGFEVENT_INTERRUPT_SOFTWARE) == true;
1578
1579	/*
1580	* Inform HM about changes.
1581	*/
1582	if (fChanged && HMIsEnabled(pVM))
1583	{
1584	HMR3NotifyDebugEventChanged(pVM);
1585	HMR3NotifyDebugEventChangedPerCpu(pVM, pVCpu);
1586	}
1587	}
1588	else if (HMIsEnabled(pVM))
1589	HMR3NotifyDebugEventChangedPerCpu(pVM, pVCpu);
1590
1591	return VINF_SUCCESS;
1592	}
1593
1594
1595	/**
1596	* Changes
1597	*
1598	* @returns VBox status code.
1599	* @param pUVM The user mode VM handle.
1600	* @param paConfigs The events to query and where to return the state.
1601	* @param cConfigs The number of elements in @a paConfigs.
1602	* @sa DBGFR3InterruptConfigHardware, DBGFR3InterruptConfigSoftware
1603	*/
1604	VMMR3DECL(int) DBGFR3InterruptConfigEx(PUVM pUVM, PCDBGFINTERRUPTCONFIG paConfigs, size_t cConfigs)
1605	{
1606	/*
1607	* Validate input.
1608	*/
1609	size_t i = cConfigs;
1610	while (i-- > 0)
1611	{
1612	AssertReturn(paConfigs[i].enmHardState <= DBGFINTERRUPTSTATE_DONT_TOUCH, VERR_INVALID_PARAMETER);
1613	AssertReturn(paConfigs[i].enmSoftState <= DBGFINTERRUPTSTATE_DONT_TOUCH, VERR_INVALID_PARAMETER);
1614	}
1615
1616	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1617	PVM pVM = pUVM->pVM;
1618	VM_ASSERT_VALID_EXT_RETURN(pVM, VERR_INVALID_VM_HANDLE);
1619
1620	/*
1621	* Apply the changes in EMT(0) and rendezvous with the other CPUs so they
1622	* can sync their data and execution with new debug state.
1623	*/
1624	DBGFR3INTERRUPTCONFIGEXARGS Args = { paConfigs, cConfigs, VINF_SUCCESS };
1625	int rc = VMMR3EmtRendezvous(pVM, VMMEMTRENDEZVOUS_FLAGS_TYPE_ASCENDING \| VMMEMTRENDEZVOUS_FLAGS_PRIORITY,
1626	dbgfR3InterruptConfigEx, &Args);
1627	if (RT_SUCCESS(rc))
1628	rc = Args.rc;
1629	return rc;
1630	}
1631
1632
1633	/**
1634	* Configures interception of a hardware interrupt.
1635	*
1636	* @returns VBox status code.
1637	* @param pUVM The user mode VM handle.
1638	* @param iInterrupt The interrupt number.
1639	* @param fEnabled Whether interception is enabled or not.
1640	* @sa DBGFR3InterruptSoftwareConfig, DBGFR3InterruptConfigEx
1641	*/
1642	VMMR3DECL(int) DBGFR3InterruptHardwareConfig(PUVM pUVM, uint8_t iInterrupt, bool fEnabled)
1643	{
1644	/*
1645	* Convert to DBGFR3InterruptConfigEx call.
1646	*/
1647	DBGFINTERRUPTCONFIG IntCfg = { iInterrupt, (uint8_t)fEnabled, DBGFINTERRUPTSTATE_DONT_TOUCH };
1648	return DBGFR3InterruptConfigEx(pUVM, &IntCfg, 1);
1649	}
1650
1651
1652	/**
1653	* Configures interception of a software interrupt.
1654	*
1655	* @returns VBox status code.
1656	* @param pUVM The user mode VM handle.
1657	* @param iInterrupt The interrupt number.
1658	* @param fEnabled Whether interception is enabled or not.
1659	* @sa DBGFR3InterruptHardwareConfig, DBGFR3InterruptConfigEx
1660	*/
1661	VMMR3DECL(int) DBGFR3InterruptSoftwareConfig(PUVM pUVM, uint8_t iInterrupt, bool fEnabled)
1662	{
1663	/*
1664	* Convert to DBGFR3InterruptConfigEx call.
1665	*/
1666	DBGFINTERRUPTCONFIG IntCfg = { iInterrupt, DBGFINTERRUPTSTATE_DONT_TOUCH, (uint8_t)fEnabled };
1667	return DBGFR3InterruptConfigEx(pUVM, &IntCfg, 1);
1668	}
1669
1670
1671	/**
1672	* Checks whether interception is enabled for a hardware interrupt.
1673	*
1674	* @returns true if enabled, false if not or invalid input.
1675	* @param pUVM The user mode VM handle.
1676	* @param iInterrupt The interrupt number.
1677	* @sa DBGFR3InterruptSoftwareIsEnabled, DBGF_IS_HARDWARE_INT_ENABLED,
1678	* DBGF_IS_SOFTWARE_INT_ENABLED
1679	*/
1680	VMMR3DECL(int) DBGFR3InterruptHardwareIsEnabled(PUVM pUVM, uint8_t iInterrupt)
1681	{
1682	/*
1683	* Validate input.
1684	*/
1685	UVM_ASSERT_VALID_EXT_RETURN(pUVM, false);
1686	PVM pVM = pUVM->pVM;
1687	VM_ASSERT_VALID_EXT_RETURN(pVM, false);
1688
1689	/*
1690	* Check it.
1691	*/
1692	return ASMBitTest(&pVM->dbgf.s.bmHardIntBreakpoints, iInterrupt);
1693	}
1694
1695
1696	/**
1697	* Checks whether interception is enabled for a software interrupt.
1698	*
1699	* @returns true if enabled, false if not or invalid input.
1700	* @param pUVM The user mode VM handle.
1701	* @param iInterrupt The interrupt number.
1702	* @sa DBGFR3InterruptHardwareIsEnabled, DBGF_IS_SOFTWARE_INT_ENABLED,
1703	* DBGF_IS_HARDWARE_INT_ENABLED,
1704	*/
1705	VMMR3DECL(int) DBGFR3InterruptSoftwareIsEnabled(PUVM pUVM, uint8_t iInterrupt)
1706	{
1707	/*
1708	* Validate input.
1709	*/
1710	UVM_ASSERT_VALID_EXT_RETURN(pUVM, false);
1711	PVM pVM = pUVM->pVM;
1712	VM_ASSERT_VALID_EXT_RETURN(pVM, false);
1713
1714	/*
1715	* Check it.
1716	*/
1717	return ASMBitTest(&pVM->dbgf.s.bmSoftIntBreakpoints, iInterrupt);
1718	}
1719
1720
1721
1722	/**
1723	* Call this to single step programmatically.
1724	*
1725	* You must pass down the return code to the EM loop! That's
1726	* where the actual single stepping take place (at least in the
1727	* current implementation).
1728	*
1729	* @returns VINF_EM_DBG_STEP
1730	*
1731	* @param pVCpu The cross context virtual CPU structure.
1732	*
1733	* @thread VCpu EMT
1734	* @internal
1735	*/
1736	VMMR3_INT_DECL(int) DBGFR3PrgStep(PVMCPU pVCpu)
1737	{
1738	VMCPU_ASSERT_EMT(pVCpu);
1739
1740	pVCpu->dbgf.s.fSingleSteppingRaw = true;
1741	return VINF_EM_DBG_STEP;
1742	}
1743
1744
1745	/**
1746	* Inject an NMI into a running VM (only VCPU 0!)
1747	*
1748	* @returns VBox status code.
1749	* @param pUVM The user mode VM structure.
1750	* @param idCpu The ID of the CPU to inject the NMI on.
1751	*/
1752	VMMR3DECL(int) DBGFR3InjectNMI(PUVM pUVM, VMCPUID idCpu)
1753	{
1754	UVM_ASSERT_VALID_EXT_RETURN(pUVM, VERR_INVALID_VM_HANDLE);
1755	PVM pVM = pUVM->pVM;
1756	VM_ASSERT_VALID_EXT_RETURN(pVM, VERR_INVALID_VM_HANDLE);
1757	AssertReturn(idCpu < pVM->cCpus, VERR_INVALID_CPU_ID);
1758
1759	/** @todo Implement generic NMI injection. */
1760	if (!HMIsEnabled(pVM))
1761	return VERR_NOT_SUP_IN_RAW_MODE;
1762
1763	VMCPU_FF_SET(&pVM->aCpus[idCpu], VMCPU_FF_INTERRUPT_NMI);
1764	return VINF_SUCCESS;
1765	}
1766

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

source: vbox/trunk/src/VBox/VMM/VMMR3/DBGF.cpp@ 61766

Download in other formats: