DrvChar.cpp revision c28fa006ba669ad8f26ae31d00a338379c04ea1b
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsync * VBox stream I/O devices: Generic char driver
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * available from http://www.virtualbox.org. This file is free software;
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * you can redistribute it and/or modify it under the terms of the GNU
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * General Public License (GPL) as published by the Free Software
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * additional information or have any questions.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/*******************************************************************************
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync* Header Files *
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync*******************************************************************************/
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsync/*******************************************************************************
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsync* Defined Constants And Macros *
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsync*******************************************************************************/
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync/** Size of the send fifo queue (in bytes) */
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync/** Converts a pointer to DRVCHAR::ICharConnector to a PDRVCHAR. */
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync#define PDMICHAR_2_DRVCHAR(pInterface) RT_FROM_MEMBER(pInterface, DRVCHAR, ICharConnector)
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/*******************************************************************************
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync* Structures and Typedefs *
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync*******************************************************************************/
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Char driver instance data.
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync * @implements PDMICHARCONNECTOR
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsynctypedef struct DRVCHAR
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /** Pointer to the driver instance structure. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /** Pointer to the char port interface of the driver/device above us. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /** Pointer to the stream interface of the driver below us. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /** Our char interface. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /** Flag to notify the receive thread it should terminate. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync volatile bool fShutdown;
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /** Receive thread ID. */
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync /** Send thread ID. */
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync /** Send event semephore */
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync /** Internal send FIFO queue */
fe96bc0e43d9c137304462ef8c2d79cbff22446fvboxsync /** Read/write statistics */
fa033b734cf3b131680f290326ccbbd23c42946bvboxsyncAssertCompileMemberAlignment(DRVCHAR, StatBytesRead, 8);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/* -=-=-=-=- IBase -=-=-=-=- */
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsync * @interface_method_impl{PDMIBASE,pfnQueryInterface}
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsyncstatic DECLCALLBACK(void *) drvCharQueryInterface(PPDMIBASE pInterface, const char *pszIID)
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync PPDMDRVINS pDrvIns = PDMIBASE_2_PDMDRV(pInterface);
a39ea3668b7019c23a68936259545f9b71bce1aavboxsync PDMIBASE_RETURN_INTERFACE(pszIID, PDMIBASE, &pDrvIns->IBase);
a39ea3668b7019c23a68936259545f9b71bce1aavboxsync PDMIBASE_RETURN_INTERFACE(pszIID, PDMICHARCONNECTOR, &pThis->ICharConnector);
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync/* -=-=-=-=- ICharConnector -=-=-=-=- */
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync/** @copydoc PDMICHARCONNECTOR::pfnWrite */
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsyncstatic DECLCALLBACK(int) drvCharWrite(PPDMICHARCONNECTOR pInterface, const void *pvBuf, size_t cbWrite)
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync LogFlow(("%s: pvBuf=%#p cbWrite=%d\n", __FUNCTION__, pvBuf, cbWrite));
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync/** @copydoc PDMICHARCONNECTOR::pfnSetParameters */
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsyncstatic DECLCALLBACK(int) drvCharSetParameters(PPDMICHARCONNECTOR pInterface, unsigned Bps, char chParity, unsigned cDataBits, unsigned cStopBits)
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync /*PDRVCHAR pThis = PDMICHAR_2_DRVCHAR(pInterface); - unused*/
e3f5c51715cbf77ae2d2e9d05bafd00d69b1bec9vboxsync LogFlow(("%s: Bps=%u chParity=%c cDataBits=%u cStopBits=%u\n", __FUNCTION__, Bps, chParity, cDataBits, cStopBits));
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync/* -=-=-=-=- receive thread -=-=-=-=- */
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync * Send thread loop.
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync * @returns 0 on success.
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync * @param ThreadSelf Thread handle to this thread.
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync * @param pvUser User argument.
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsyncstatic DECLCALLBACK(int) drvCharSendLoop(RTTHREAD ThreadSelf, void *pvUser)
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync int rc = RTSemEventWait(pThis->SendSem, RT_INDEFINITE_WAIT);
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync * Write the character to the attached stream (if present).
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync while (pThis->iSendQueueTail != pThis->iSendQueueHead)
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync rc = pThis->pDrvStream->pfnWrite(pThis->pDrvStream, &pThis->aSendQueue[pThis->iSendQueueTail], &cbProcessed);
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync /* Normal case, just means that the stream didn't accept a new
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync * character before the timeout elapsed. Just retry. */
fe813b3594039ba864493438e78ee0e7132bc445vboxsync LogFlow(("Write failed with %Rrc; skipping\n", rc));
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/* -=-=-=-=- receive thread -=-=-=-=- */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Receive thread loop.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @returns 0 on success.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @param ThreadSelf Thread handle to this thread.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @param pvUser User argument.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsyncstatic DECLCALLBACK(int) drvCharReceiveLoop(RTTHREAD ThreadSelf, void *pvUser)
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* Get block of data from stream driver. */
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync rc = pThis->pDrvStream->pfnRead(pThis->pDrvStream, aBuffer, &cbRemaining);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* Send data to guest. */
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync rc = pThis->pDrvCharPort->pfnNotifyRead(pThis->pDrvCharPort, pBuffer, &cbProcessed);
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync STAM_COUNTER_ADD(&pThis->StatBytesRead, cbProcessed);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* Normal case, just means that the guest didn't accept a new
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * character before the timeout elapsed. Just retry. */
362838d79d234a41380be42aae9118850cc3c929vboxsync * Set the modem lines.
362838d79d234a41380be42aae9118850cc3c929vboxsync * @returns VBox status code
362838d79d234a41380be42aae9118850cc3c929vboxsync * @param pInterface Pointer to the interface structure.
bc36547e8dd3d35e5f756643a267bbe01e2c1d4cvboxsync * @param RequestToSend Set to true if this control line should be made active.
bc36547e8dd3d35e5f756643a267bbe01e2c1d4cvboxsync * @param DataTerminalReady Set to true if this control line should be made active.
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsyncstatic DECLCALLBACK(int) drvCharSetModemLines(PPDMICHARCONNECTOR pInterface, bool RequestToSend, bool DataTerminalReady)
362838d79d234a41380be42aae9118850cc3c929vboxsync /* Nothing to do here. */
22bdb1ce26b2d5a41d1b071c16f1078e5348bb0dvboxsync * Sets the TD line into break condition.
22bdb1ce26b2d5a41d1b071c16f1078e5348bb0dvboxsync * @returns VBox status code.
22bdb1ce26b2d5a41d1b071c16f1078e5348bb0dvboxsync * @param pInterface Pointer to the interface structure containing the called function pointer.
22bdb1ce26b2d5a41d1b071c16f1078e5348bb0dvboxsync * @param fBreak Set to true to let the device send a break false to put into normal operation.
22bdb1ce26b2d5a41d1b071c16f1078e5348bb0dvboxsync * @thread Any thread.
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsyncstatic DECLCALLBACK(int) drvCharSetBreak(PPDMICHARCONNECTOR pInterface, bool fBreak)
22bdb1ce26b2d5a41d1b071c16f1078e5348bb0dvboxsync /* Nothing to do here. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/* -=-=-=-=- driver interface -=-=-=-=- */
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync * Destruct a char driver instance.
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync * Most VM resources are freed by the VM. This callback is provided so that
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync * any non-VM resources can be freed correctly.
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync * @param pDrvIns The driver instance data.
e74eef731a813e4e06680c587a6759b9974b29c9vboxsyncstatic DECLCALLBACK(void) drvCharDestruct(PPDMDRVINS pDrvIns)
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync LogFlow(("%s: iInstance=%d\n", __FUNCTION__, pDrvIns->iInstance));
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync LogRel(("Char%d: receive thread did not terminate\n", pDrvIns->iInstance));
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync /* Empty the send queue */
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync LogRel(("Char%d: send thread did not terminate\n", pDrvIns->iInstance));
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Construct a char driver instance.
cba6719bd64ec749967bbe931230452664109857vboxsync * @copydoc FNPDMDRVCONSTRUCT
c28fa006ba669ad8f26ae31d00a338379c04ea1bvboxsyncstatic DECLCALLBACK(int) drvCharConstruct(PPDMDRVINS pDrvIns, PCFGMNODE pCfg, uint32_t fFlags)
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync LogFlow(("%s: iInstance=%d\n", __FUNCTION__, pDrvIns->iInstance));
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Init basic data members and interfaces.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* IBase. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync pDrvIns->IBase.pfnQueryInterface = drvCharQueryInterface;
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync /* ICharConnector. */
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync pThis->ICharConnector.pfnSetParameters = drvCharSetParameters;
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync pThis->ICharConnector.pfnSetModemLines = drvCharSetModemLines;
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync pThis->ICharConnector.pfnSetBreak = drvCharSetBreak;
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Get the ICharPort interface of the above driver/device.
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync pThis->pDrvCharPort = PDMIBASE_QUERY_INTERFACE(pDrvIns->pUpBase, PDMICHARPORT);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync return PDMDrvHlpVMSetError(pDrvIns, VERR_PDM_MISSING_INTERFACE_ABOVE, RT_SRC_POS, N_("Char#%d has no char port interface above"), pDrvIns->iInstance);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Attach driver below and query its stream interface.
30adc6dd25ed9fef4d800a6d9f1ab7e765b4c340vboxsync return rc; /* Don't call PDMDrvHlpVMSetError here as we assume that the driver already set an appropriate error */
da3503c04ce76e653401396fe2795a9bc2427a1dvboxsync pThis->pDrvStream = PDMIBASE_QUERY_INTERFACE(pBase, PDMISTREAM);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync return PDMDrvHlpVMSetError(pDrvIns, VERR_PDM_MISSING_INTERFACE_BELOW, RT_SRC_POS, N_("Char#%d has no stream interface below"), pDrvIns->iInstance);
801238b286a80a5dd67ba56a1f26c0bc98a2a1eavboxsync * Don't start the receive thread if the driver doesn't support reading
801238b286a80a5dd67ba56a1f26c0bc98a2a1eavboxsync rc = RTThreadCreate(&pThis->ReceiveThread, drvCharReceiveLoop, (void *)pThis, 0, RTTHREADTYPE_IO, RTTHREADFLAGS_WAITABLE, "CharRecv");
801238b286a80a5dd67ba56a1f26c0bc98a2a1eavboxsync return PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, N_("Char#%d cannot create receive thread"), pDrvIns->iInstance);
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync rc = RTThreadCreate(&pThis->SendThread, drvCharSendLoop, (void *)pThis, 0, RTTHREADTYPE_IO, RTTHREADFLAGS_WAITABLE, "CharSend");
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync return PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, N_("Char#%d cannot create send thread"), pDrvIns->iInstance);
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync PDMDrvHlpSTAMRegisterF(pDrvIns, &pThis->StatBytesWritten, STAMTYPE_COUNTER, STAMVISIBILITY_USED, STAMUNIT_BYTES, "Nr of bytes written", "/Devices/Char%d/Written", pDrvIns->iInstance);
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync PDMDrvHlpSTAMRegisterF(pDrvIns, &pThis->StatBytesRead, STAMTYPE_COUNTER, STAMVISIBILITY_USED, STAMUNIT_BYTES, "Nr of bytes read", "/Devices/Char%d/Read", pDrvIns->iInstance);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Char driver registration record.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* u32Version */
5b465a7c1237993faf8bb50120d247f3f0319adavboxsync /* szName */
ad77e3ec3cde24263bc7537575f5cae442bee3b1vboxsync /* szRCMod */
ad77e3ec3cde24263bc7537575f5cae442bee3b1vboxsync /* szR0Mod */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pszDescription */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync "Generic char driver.",
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* fFlags */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* fClass. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* cMaxInstances */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* cbInstance */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnConstruct */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnDestruct */
ad77e3ec3cde24263bc7537575f5cae442bee3b1vboxsync /* pfnRelocate */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnIOCtl */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnPowerOn */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnReset */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnSuspend */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnResume */
cba6719bd64ec749967bbe931230452664109857vboxsync /* pfnAttach */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnDetach */
cba6719bd64ec749967bbe931230452664109857vboxsync /* pfnPowerOff */
cba6719bd64ec749967bbe931230452664109857vboxsync /* pfnSoftReset */
cba6719bd64ec749967bbe931230452664109857vboxsync /* u32EndVersion */