DrvChar.cpp@ 68637

Last change on this file since 68637 was 68637, checked in by vboxsync, 7 years ago
DevChar.cpp: doxygen fix attempt
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 19.1 KB

Line
1	/* $Id: DrvChar.cpp 68637 2017-09-05 13:28:14Z vboxsync $ */
2	/** @file
3	* Driver that adapts PDMISTREAM into PDMICHARCONNECTOR / PDMICHARPORT.
4	*
5	* Converts synchronous calls (PDMICHARCONNECTOR::pfnWrite, PDMISTREAM::pfnRead)
6	* into asynchronous ones.
7	*
8	* Note that we don't use a send buffer here to be able to handle
9	* dropping of bytes for xmit at device level.
10	*/
11
12	/*
13	* Copyright (C) 2006-2016 Oracle Corporation
14	*
15	* This file is part of VirtualBox Open Source Edition (OSE), as
16	* available from http://www.virtualbox.org. This file is free software;
17	* you can redistribute it and/or modify it under the terms of the GNU
18	* General Public License (GPL) as published by the Free Software
19	* Foundation, in version 2 as it comes in the "COPYING" file of the
20	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
21	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
22	*/
23
24
25	/*********************************************************************************************************************************
26	* Header Files *
27	*********************************************************************************************************************************/
28	#define LOG_GROUP LOG_GROUP_DRV_CHAR
29	#include <VBox/vmm/pdmdrv.h>
30	#include <iprt/asm.h>
31	#include <iprt/assert.h>
32	#include <iprt/stream.h>
33	#include <iprt/semaphore.h>
34	#include <iprt/uuid.h>
35
36	#include "VBoxDD.h"
37
38
39	/*********************************************************************************************************************************
40	* Defined Constants And Macros *
41	*********************************************************************************************************************************/
42	/** Converts a pointer to DRVCHAR::ICharConnector to a PDRVCHAR. */
43	#define PDMICHAR_2_DRVCHAR(pInterface) RT_FROM_MEMBER(pInterface, DRVCHAR, ICharConnector)
44
45
46	/*********************************************************************************************************************************
47	* Structures and Typedefs *
48	*********************************************************************************************************************************/
49	/**
50	* Char driver instance data.
51	*
52	* @implements PDMICHARCONNECTOR
53	*/
54	typedef struct DRVCHAR
55	{
56	/** Pointer to the driver instance structure. */
57	PPDMDRVINS pDrvIns;
58	/** Pointer to the char port interface of the driver/device above us. */
59	PPDMICHARPORT pDrvCharPort;
60	/** Pointer to the stream interface of the driver below us. */
61	PPDMISTREAM pDrvStream;
62	/** Our char interface. */
63	PDMICHARCONNECTOR ICharConnector;
64	/** Flag to notify the receive thread it should terminate. */
65	volatile bool fShutdown;
66	/** Receive thread ID. */
67	RTTHREAD ReceiveThread;
68	/** Send thread ID. */
69	RTTHREAD SendThread;
70	/** Send event semaphore */
71	RTSEMEVENT SendSem;
72
73	/** Internal send FIFO queue */
74	uint8_t volatile u8SendByte;
75	bool volatile fSending;
76	uint8_t Alignment[2];
77
78	/** Read/write statistics */
79	STAMCOUNTER StatBytesRead;
80	STAMCOUNTER StatBytesWritten;
81	} DRVCHAR, *PDRVCHAR;
82	AssertCompileMemberAlignment(DRVCHAR, StatBytesRead, 8);
83
84
85
86
87	/* -=-=-=-=- IBase -=-=-=-=- */
88
89	/**
90	* @interface_method_impl{PDMIBASE,pfnQueryInterface}
91	*/
92	static DECLCALLBACK(void ) drvCharQueryInterface(PPDMIBASE pInterface, const char pszIID)
93	{
94	PPDMDRVINS pDrvIns = PDMIBASE_2_PDMDRV(pInterface);
95	PDRVCHAR pThis = PDMINS_2_DATA(pDrvIns, PDRVCHAR);
96
97	PDMIBASE_RETURN_INTERFACE(pszIID, PDMIBASE, &pDrvIns->IBase);
98	PDMIBASE_RETURN_INTERFACE(pszIID, PDMICHARCONNECTOR, &pThis->ICharConnector);
99	return NULL;
100	}
101
102
103	/* -=-=-=-=- ICharConnector -=-=-=-=- */
104
105	/**
106	* @interface_method_impl{PDMICHARCONNECTOR,pfnWrite}
107	*/
108	static DECLCALLBACK(int) drvCharWrite(PPDMICHARCONNECTOR pInterface, const void *pvBuf, size_t cbWrite)
109	{
110	PDRVCHAR pThis = PDMICHAR_2_DRVCHAR(pInterface);
111	const char pbBuffer = (const char )pvBuf;
112
113	LogFlow(("%s: pvBuf=%#p cbWrite=%d\n", __FUNCTION__, pvBuf, cbWrite));
114
115	for (uint32_t i = 0; i < cbWrite; i++)
116	{
117	if (ASMAtomicXchgBool(&pThis->fSending, true))
118	return VERR_BUFFER_OVERFLOW;
119
120	pThis->u8SendByte = pbBuffer[i];
121	RTSemEventSignal(pThis->SendSem);
122	STAM_COUNTER_INC(&pThis->StatBytesWritten);
123	}
124	return VINF_SUCCESS;
125	}
126
127
128	/**
129	* @interface_method_impl{PDMICHARCONNECTOR,pfnSetParameters}
130	*/
131	static DECLCALLBACK(int) drvCharSetParameters(PPDMICHARCONNECTOR pInterface, unsigned Bps, char chParity,
132	unsigned cDataBits, unsigned cStopBits)
133	{
134	RT_NOREF(pInterface, Bps, chParity, cDataBits, cStopBits);
135	/PDRVCHAR pThis = PDMICHAR_2_DRVCHAR(pInterface); - unused/
136
137	LogFlow(("%s: Bps=%u chParity=%c cDataBits=%u cStopBits=%u\n", __FUNCTION__, Bps, chParity, cDataBits, cStopBits));
138	return VINF_SUCCESS;
139	}
140
141
142	/* -=-=-=-=- receive thread -=-=-=-=- */
143
144	/**
145	* Send thread loop - pushes data down thru the driver chain.
146	*
147	* @returns 0 on success.
148	* @param hThreadSelf Thread handle to this thread.
149	* @param pvUser User argument.
150	*/
151	static DECLCALLBACK(int) drvCharSendLoop(RTTHREAD hThreadSelf, void *pvUser)
152	{
153	RT_NOREF(hThreadSelf);
154	PDRVCHAR pThis = (PDRVCHAR)pvUser;
155
156	int rc = VINF_SUCCESS;
157	while (!pThis->fShutdown)
158	{
159	RTMSINTERVAL cMillies = (rc == VERR_TIMEOUT) ? 50 : RT_INDEFINITE_WAIT;
160	rc = RTSemEventWait(pThis->SendSem, cMillies);
161	if ( RT_FAILURE(rc)
162	&& rc != VERR_TIMEOUT)
163	break;
164
165	/*
166	* Write the character to the attached stream (if present).
167	*/
168	if ( pThis->fShutdown
169	\|\| !pThis->pDrvStream)
170	break;
171
172	size_t cbProcessed = 1;
173	uint8_t ch = pThis->u8SendByte;
174	rc = pThis->pDrvStream->pfnWrite(pThis->pDrvStream, &ch, &cbProcessed);
175	if (RT_SUCCESS(rc))
176	{
177	ASMAtomicXchgBool(&pThis->fSending, false);
178	Assert(cbProcessed == 1);
179	}
180	else if (rc == VERR_TIMEOUT)
181	{
182	/* Normal case, just means that the stream didn't accept a new
183	* character before the timeout elapsed. Just retry. */
184
185	/* do not change the rc status here, otherwise the (rc == VERR_TIMEOUT) branch
186	* in the wait above will never get executed */
187	/* rc = VINF_SUCCESS; */
188	}
189	else
190	{
191	LogRel(("Write failed with %Rrc; skipping\n", rc));
192	break;
193	}
194	}
195
196	return VINF_SUCCESS;
197	}
198
199
200	/* -=-=-=-=- receive thread -=-=-=-=- */
201
202	/**
203	* Receive thread loop.
204	*
205	* @returns 0 on success.
206	* @param hThreadSelf Thread handle to this thread.
207	* @param pvUser User argument.
208	*
209	* @todo This thread isn't managed correctly wrt to the VM state.
210	* @todo This thread isn't managed correctly wrt to the VM state.
211	* @todo This thread isn't managed correctly wrt to the VM state.
212	* @todo This thread isn't managed correctly wrt to the VM state.
213	* @todo This thread isn't managed correctly wrt to the VM state.
214	* @todo This thread isn't managed correctly wrt to the VM state.
215	* @todo This thread isn't managed correctly wrt to the VM state.
216	* @todo This thread isn't managed correctly wrt to the VM state.
217	* @todo This thread isn't managed correctly wrt to the VM state.
218	* @todo This thread isn't managed correctly wrt to the VM state.
219	* @todo This thread isn't managed correctly wrt to the VM state.
220	* @todo This thread isn't managed correctly wrt to the VM state.
221	* @todo This thread isn't managed correctly wrt to the VM state.
222	* @todo This thread isn't managed correctly wrt to the VM state.
223	* @todo This thread isn't managed correctly wrt to the VM state.
224	* @todo This thread isn't managed correctly wrt to the VM state.
225	* @todo This thread isn't managed correctly wrt to the VM state.
226	* @todo This thread isn't managed correctly wrt to the VM state.
227	* @todo This thread isn't managed correctly wrt to the VM state.
228	* @todo This thread isn't managed correctly wrt to the VM state.
229	* @todo This thread isn't managed correctly wrt to the VM state.
230	* @todo This thread isn't managed correctly wrt to the VM state.
231	* @todo This thread isn't managed correctly wrt to the VM state.
232	* @todo This thread isn't managed correctly wrt to the VM state.
233	* @todo This thread isn't managed correctly wrt to the VM state.
234	* @todo This thread isn't managed correctly wrt to the VM state.
235	* @todo This thread isn't managed correctly wrt to the VM state.
236	* @todo This thread isn't managed correctly wrt to the VM state.
237	* @todo This thread isn't managed correctly wrt to the VM state.
238	* @todo This thread isn't managed correctly wrt to the VM state.
239	* @todo This thread isn't managed correctly wrt to the VM state.
240	* @todo This thread isn't managed correctly wrt to the VM state.
241	*
242	* It's possible to end up in the APIC code while the VM is being destroyed!
243	* @code
244	0:018> k
245	# Child-SP RetAddr Call Site
246	00 00000000`2061f1b0 00007ffe`42a889d9 VBoxVMM!apicReadRaw32+0x78 [e:\vbox\svn\trunk\src\vbox\vmm\vmmall\apicall.cpp @ 462]
247	01 00000000`2061f1f0 00007ffe`42916fc2 VBoxVMM!APICLocalInterrupt+0x189 [e:\vbox\svn\trunk\src\vbox\vmm\vmmall\apicall.cpp @ 2524]
248	02 00000000`2061f320 00007ffe`41b96937 VBoxVMM!pdmR3PicHlp_ClearInterruptFF+0x172 [e:\vbox\svn\trunk\src\vbox\vmm\vmmr3\pdmdevmischlp.cpp @ 67]
249	03 00000000`2061f360 00007ffe`41b961a8 VBoxDD!pic_update_irq+0x327 [e:\vbox\svn\trunk\src\vbox\devices\pc\devpic.cpp @ 318]
250	04 00000000`2061f3f0 00007ffe`42bcbaa3 VBoxDD!picSetIrq+0x2b8 [e:\vbox\svn\trunk\src\vbox\devices\pc\devpic.cpp @ 352]
251	05 00000000`2061f450 00007ffe`42905dff VBoxVMM!PDMIsaSetIrq+0xe3 [e:\vbox\svn\trunk\src\vbox\vmm\vmmall\pdmall.cpp @ 138]
252	06 00000000`2061f490 00007ffe`41c06db4 VBoxVMM!pdmR3DevHlp_ISASetIrq+0x2df [e:\vbox\svn\trunk\src\vbox\vmm\vmmr3\pdmdevhlp.cpp @ 1804]
253	07 00000000`2061f500 00007ffe`41c08d39 VBoxDD!PDMDevHlpISASetIrqNoWait+0x44 [e:\vbox\svn\trunk\include\vbox\vmm\pdmdev.h @ 4972]
254	08 00000000`2061f530 00007ffe`41c08a44 VBoxDD!serial_update_irq+0x1c9 [e:\vbox\svn\trunk\src\vbox\devices\serial\devserial.cpp @ 326]
255	09 00000000`2061f590 00007ffe`41c08814 VBoxDD!serial_receive+0x134 [e:\vbox\svn\trunk\src\vbox\devices\serial\devserial.cpp @ 718]
256	0a 00000000`2061f5d0 00007ffe`41c1d894 VBoxDD!serialNotifyRead+0x124 [e:\vbox\svn\trunk\src\vbox\devices\serial\devserial.cpp @ 744]
257	0b 00000000`2061f630 00007ffe`43a6250f VBoxDD!drvCharReceiveLoop+0x194 [e:\vbox\svn\trunk\src\vbox\devices\serial\drvchar.cpp @ 241]
258	0c 00000000`2061f800 00007ffe`43b8ddbf VBoxRT!rtThreadMain+0x1bf [e:\vbox\svn\trunk\src\vbox\runtime\common\misc\thread.cpp @ 717]
259	0d 00000000`2061f880 00000000`52971d9f VBoxRT!rtThreadNativeMain+0xcf [e:\vbox\svn\trunk\src\vbox\runtime\r3\win\thread-win.cpp @ 252]
260	0e 00000000`2061f8d0 00000000`52971e3b MSVCR100!endthreadex+0x43
261	@endcode
262	*
263	*/
264	static DECLCALLBACK(int) drvCharReceiveLoop(RTTHREAD hThreadSelf, void *pvUser)
265	{
266	RT_NOREF(hThreadSelf);
267	PDRVCHAR pThis = (PDRVCHAR)pvUser;
268	char abBuffer[256];
269	char *pbRemaining = abBuffer;
270	size_t cbRemaining = 0;
271	int rc;
272
273	while (!pThis->fShutdown)
274	{
275	if (!cbRemaining)
276	{
277	/* Get block of data from stream driver. */
278	if (pThis->pDrvStream)
279	{
280	pbRemaining = abBuffer;
281	cbRemaining = sizeof(abBuffer);
282	rc = pThis->pDrvStream->pfnRead(pThis->pDrvStream, abBuffer, &cbRemaining);
283	if (RT_FAILURE(rc))
284	{
285	LogFlow(("Read failed with %Rrc\n", rc));
286	break;
287	}
288	}
289	else
290	RTThreadSleep(100);
291	}
292	else
293	{
294	/* Send data to guest. */
295	size_t cbProcessed = cbRemaining;
296	rc = pThis->pDrvCharPort->pfnNotifyRead(pThis->pDrvCharPort, pbRemaining, &cbProcessed);
297	if (RT_SUCCESS(rc))
298	{
299	Assert(cbProcessed);
300	pbRemaining += cbProcessed;
301	cbRemaining -= cbProcessed;
302	STAM_COUNTER_ADD(&pThis->StatBytesRead, cbProcessed);
303	}
304	else if (rc == VERR_TIMEOUT)
305	{
306	/* Normal case, just means that the guest didn't accept a new
307	* character before the timeout elapsed. Just retry. */
308	rc = VINF_SUCCESS;
309	}
310	else
311	{
312	LogFlow(("NotifyRead failed with %Rrc\n", rc));
313	break;
314	}
315	}
316	}
317
318	return VINF_SUCCESS;
319	}
320
321
322	/**
323	* @callback_method_impl{PDMICHARCONNECTOR,pfnSetModemLines}
324	*/
325	static DECLCALLBACK(int) drvCharSetModemLines(PPDMICHARCONNECTOR pInterface, bool fRequestToSend, bool fDataTerminalReady)
326	{
327	/* Nothing to do here. */
328	RT_NOREF(pInterface, fRequestToSend, fDataTerminalReady);
329	return VINF_SUCCESS;
330	}
331
332
333	/**
334	* @callback_method_impl{PDMICHARCONNECTOR,pfnSetBreak}
335	*/
336	static DECLCALLBACK(int) drvCharSetBreak(PPDMICHARCONNECTOR pInterface, bool fBreak)
337	{
338	/* Nothing to do here. */
339	RT_NOREF(pInterface, fBreak);
340	return VINF_SUCCESS;
341	}
342
343
344	/* -=-=-=-=- driver interface -=-=-=-=- */
345
346	/**
347	* Destruct a char driver instance.
348	*
349	* Most VM resources are freed by the VM. This callback is provided so that
350	* any non-VM resources can be freed correctly.
351	*
352	* @param pDrvIns The driver instance data.
353	*/
354	static DECLCALLBACK(void) drvCharDestruct(PPDMDRVINS pDrvIns)
355	{
356	PDRVCHAR pThis = PDMINS_2_DATA(pDrvIns, PDRVCHAR);
357	LogFlow(("%s: iInstance=%d\n", __FUNCTION__, pDrvIns->iInstance));
358	PDMDRV_CHECK_VERSIONS_RETURN_VOID(pDrvIns);
359
360	/*
361	* Tell the threads to shut down.
362	*/
363	pThis->fShutdown = true;
364	if (pThis->SendSem != NIL_RTSEMEVENT)
365	{
366	RTSemEventSignal(pThis->SendSem);
367	pThis->SendSem = NIL_RTSEMEVENT;
368	}
369
370	/*
371	* Wait for the threads.
372	* ASSUMES that PDM destroys the driver chain from the bottom and up.
373	*/
374	if (pThis->ReceiveThread != NIL_RTTHREAD)
375	{
376	int rc = RTThreadWait(pThis->ReceiveThread, 30000, NULL);
377	if (RT_SUCCESS(rc))
378	pThis->ReceiveThread = NIL_RTTHREAD;
379	else
380	LogRel(("Char%d: receive thread did not terminate (%Rrc)\n", pDrvIns->iInstance, rc));
381	}
382
383	if (pThis->SendThread != NIL_RTTHREAD)
384	{
385	int rc = RTThreadWait(pThis->SendThread, 30000, NULL);
386	if (RT_SUCCESS(rc))
387	pThis->SendThread = NIL_RTTHREAD;
388	else
389	LogRel(("Char%d: send thread did not terminate (%Rrc)\n", pDrvIns->iInstance, rc));
390	}
391
392	if (pThis->SendSem != NIL_RTSEMEVENT)
393	{
394	RTSemEventDestroy(pThis->SendSem);
395	pThis->SendSem = NIL_RTSEMEVENT;
396	}
397	}
398
399
400	/**
401	* Construct a char driver instance.
402	*
403	* @copydoc FNPDMDRVCONSTRUCT
404	*/
405	static DECLCALLBACK(int) drvCharConstruct(PPDMDRVINS pDrvIns, PCFGMNODE pCfg, uint32_t fFlags)
406	{
407	RT_NOREF(pCfg);
408	PDMDRV_CHECK_VERSIONS_RETURN(pDrvIns);
409	PDRVCHAR pThis = PDMINS_2_DATA(pDrvIns, PDRVCHAR);
410	LogFlow(("%s: iInstance=%d\n", __FUNCTION__, pDrvIns->iInstance));
411
412	/*
413	* Init basic data members and interfaces.
414	*/
415	pThis->fShutdown = false;
416	pThis->ReceiveThread = NIL_RTTHREAD;
417	pThis->SendThread = NIL_RTTHREAD;
418	pThis->SendSem = NIL_RTSEMEVENT;
419	/* IBase. */
420	pDrvIns->IBase.pfnQueryInterface = drvCharQueryInterface;
421	/* ICharConnector. */
422	pThis->ICharConnector.pfnWrite = drvCharWrite;
423	pThis->ICharConnector.pfnSetParameters = drvCharSetParameters;
424	pThis->ICharConnector.pfnSetModemLines = drvCharSetModemLines;
425	pThis->ICharConnector.pfnSetBreak = drvCharSetBreak;
426
427	/*
428	* Get the ICharPort interface of the above driver/device.
429	*/
430	pThis->pDrvCharPort = PDMIBASE_QUERY_INTERFACE(pDrvIns->pUpBase, PDMICHARPORT);
431	if (!pThis->pDrvCharPort)
432	return PDMDrvHlpVMSetError(pDrvIns, VERR_PDM_MISSING_INTERFACE_ABOVE, RT_SRC_POS, N_("Char#%d has no char port interface above"), pDrvIns->iInstance);
433
434	/*
435	* Attach driver below and query its stream interface.
436	*/
437	PPDMIBASE pBase;
438	int rc = PDMDrvHlpAttach(pDrvIns, fFlags, &pBase);
439	if (RT_FAILURE(rc))
440	return rc; /* Don't call PDMDrvHlpVMSetError here as we assume that the driver already set an appropriate error */
441	pThis->pDrvStream = PDMIBASE_QUERY_INTERFACE(pBase, PDMISTREAM);
442	if (!pThis->pDrvStream)
443	return PDMDrvHlpVMSetError(pDrvIns, VERR_PDM_MISSING_INTERFACE_BELOW, RT_SRC_POS, N_("Char#%d has no stream interface below"), pDrvIns->iInstance);
444
445	/*
446	* Don't start the receive thread if the driver doesn't support reading
447	*/
448	if (pThis->pDrvStream->pfnRead)
449	{
450	rc = RTThreadCreate(&pThis->ReceiveThread, drvCharReceiveLoop, (void *)pThis, 0,
451	RTTHREADTYPE_IO, RTTHREADFLAGS_WAITABLE, "CharRecv");
452	if (RT_FAILURE(rc))
453	return PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, N_("Char#%d cannot create receive thread"), pDrvIns->iInstance);
454	}
455
456	rc = RTSemEventCreate(&pThis->SendSem);
457	AssertRCReturn(rc, rc);
458
459	rc = RTThreadCreate(&pThis->SendThread, drvCharSendLoop, (void *)pThis, 0,
460	RTTHREADTYPE_IO, RTTHREADFLAGS_WAITABLE, "CharSend");
461	if (RT_FAILURE(rc))
462	return PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, N_("Char#%d cannot create send thread"), pDrvIns->iInstance);
463
464
465	PDMDrvHlpSTAMRegisterF(pDrvIns, &pThis->StatBytesWritten, STAMTYPE_COUNTER, STAMVISIBILITY_USED, STAMUNIT_BYTES, "Nr of bytes written", "/Devices/Char%d/Written", pDrvIns->iInstance);
466	PDMDrvHlpSTAMRegisterF(pDrvIns, &pThis->StatBytesRead, STAMTYPE_COUNTER, STAMVISIBILITY_USED, STAMUNIT_BYTES, "Nr of bytes read", "/Devices/Char%d/Read", pDrvIns->iInstance);
467
468	return VINF_SUCCESS;
469	}
470
471
472	/**
473	* Char driver registration record.
474	*/
475	const PDMDRVREG g_DrvChar =
476	{
477	/* u32Version */
478	PDM_DRVREG_VERSION,
479	/* szName */
480	"Char",
481	/* szRCMod */
482	"",
483	/* szR0Mod */
484	"",
485	/* pszDescription */
486	"Generic char driver.",
487	/* fFlags */
488	PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT,
489	/* fClass. */
490	PDM_DRVREG_CLASS_CHAR,
491	/* cMaxInstances */
492	~0U,
493	/* cbInstance */
494	sizeof(DRVCHAR),
495	/* pfnConstruct */
496	drvCharConstruct,
497	/* pfnDestruct */
498	drvCharDestruct,
499	/* pfnRelocate */
500	NULL,
501	/* pfnIOCtl */
502	NULL,
503	/* pfnPowerOn */
504	NULL,
505	/* pfnReset */
506	NULL,
507	/* pfnSuspend */
508	NULL,
509	/* pfnResume */
510	NULL,
511	/* pfnAttach */
512	NULL,
513	/* pfnDetach */
514	NULL,
515	/* pfnPowerOff */
516	NULL,
517	/* pfnSoftReset */
518	NULL,
519	/* u32EndVersion */
520	PDM_DRVREG_VERSION
521	};

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

source: vbox/trunk/src/VBox/Devices/Serial/DrvChar.cpp@ 68637

Download in other formats: