DrvChar.cpp revision 1c94c0a63ba68be1a7b2c640e70d7a06464e4fca
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * VBox stream I/O devices:
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * 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*******************************************************************************/
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync/** Size of the send fifo queue (in bytes) */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/*******************************************************************************
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync* Structures and Typedefs *
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync*******************************************************************************/
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Char driver instance data.
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 */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/** Converts a pointer to DRVCHAR::IChar to a PDRVCHAR. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync#define PDMICHAR_2_DRVCHAR(pInterface) ( (PDRVCHAR)((uintptr_t)pInterface - RT_OFFSETOF(DRVCHAR, IChar)) )
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/* -=-=-=-=- IBase -=-=-=-=- */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Queries an interface to the driver.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @returns Pointer to interface.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @returns NULL if the interface was not supported by the driver.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @param pInterface Pointer to this interface structure.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @param enmInterface The requested interface identification.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsyncstatic DECLCALLBACK(void *) drvCharQueryInterface(PPDMIBASE pInterface, PDMINTERFACE enmInterface)
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync PPDMDRVINS pDrvIns = PDMIBASE_2_PDMDRV(pInterface);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/* -=-=-=-=- IChar -=-=-=-=- */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/** @copydoc PDMICHAR::pfnWrite */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsyncstatic DECLCALLBACK(int) drvCharWrite(PPDMICHAR pInterface, const void *pvBuf, size_t cbWrite)
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync LogFlow(("%s: pvBuf=%#p cbWrite=%d\n", __FUNCTION__, pvBuf, cbWrite));
aa32d4906f2f685992091893d5abdf27a2352a85vboxsync/** @copydoc PDMICHAR::pfnSetParameters */
e3f5c51715cbf77ae2d2e9d05bafd00d69b1bec9vboxsyncstatic DECLCALLBACK(int) drvCharSetParameters(PPDMICHAR pInterface, unsigned Bps, char chParity, unsigned cDataBits, unsigned cStopBits)
e3f5c51715cbf77ae2d2e9d05bafd00d69b1bec9vboxsync /*PDRVCHAR pData = 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)
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync int rc = RTSemEventWait(pData->SendSem, RT_INDEFINITE_WAIT);
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync * Write the character to the attached stream (if present).
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync while (pData->iSendQueueTail != pData->iSendQueueHead)
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync rc = pData->pDrvStream->pfnWrite(pData->pDrvStream, &pData->aSendQueue[pData->iSendQueueTail], &cbProcessed);
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync /* Normal case, just means that the stream didn't accept a new
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync * character before the timeout elapsed. Just retry. */
6a84b239fa9107dd2fd98a0baafca598a05a2c15vboxsync LogFlow(("Write failed with %Vrc; 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. */
bd96e81081052c309669f3f9b183cfec4fffbefbvboxsync rc = pData->pDrvStream->pfnRead(pData->pDrvStream, aBuffer, &cbRemaining);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* Send data to guest. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync rc = pData->pDrvCharPort->pfnNotifyRead(pData->pDrvCharPort, pBuffer, &cbProcessed);
fe96bc0e43d9c137304462ef8c2d79cbff22446fvboxsync STAM_COUNTER_ADD(&pData->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.
bc36547e8dd3d35e5f756643a267bbe01e2c1d4cvboxsyncstatic DECLCALLBACK(int) drvCharSetModemLines(PPDMICHAR pInterface, bool RequestToSend, bool DataTerminalReady)
362838d79d234a41380be42aae9118850cc3c929vboxsync /* Nothing to do here. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync/* -=-=-=-=- driver interface -=-=-=-=- */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Construct a char driver instance.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @returns VBox status.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @param pDrvIns The driver instance data.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * If the registration structure is needed,
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * pDrvIns->pDrvReg points to it.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @param pCfgHandle Configuration node handle for the driver. Use this to
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * obtain the configuration of the driver instance. It's
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * also found in pDrvIns->pCfgHandle as it's expected to
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * be used frequently in this function.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsyncstatic DECLCALLBACK(int) drvCharConstruct(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle)
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync LogFlow(("%s: iInstance=%d\n", __FUNCTION__, pDrvIns->iInstance));
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Init basic data members and interfaces.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* IBase. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync pDrvIns->IBase.pfnQueryInterface = drvCharQueryInterface;
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* IChar. */
aa32d4906f2f685992091893d5abdf27a2352a85vboxsync pData->IChar.pfnSetParameters = drvCharSetParameters;
362838d79d234a41380be42aae9118850cc3c929vboxsync pData->IChar.pfnSetModemLines = drvCharSetModemLines;
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Get the ICharPort interface of the above driver/device.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync pData->pDrvCharPort = (PPDMICHARPORT)pDrvIns->pUpBase->pfnQueryInterface(pDrvIns->pUpBase, PDMINTERFACE_CHAR_PORT);
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.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync int rc = pDrvIns->pDrvHlp->pfnAttach(pDrvIns, &pBase);
30adc6dd25ed9fef4d800a6d9f1ab7e765b4c340vboxsync return rc; /* Don't call PDMDrvHlpVMSetError here as we assume that the driver already set an appropriate error */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync pData->pDrvStream = (PPDMISTREAM)pBase->pfnQueryInterface(pBase, PDMINTERFACE_STREAM);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync return PDMDrvHlpVMSetError(pDrvIns, VERR_PDM_MISSING_INTERFACE_BELOW, RT_SRC_POS, N_("Char#%d has no stream interface below"), pDrvIns->iInstance);
c18940aaee473ca75acc33491c1dc77b3e8094e0vboxsync rc = RTThreadCreate(&pData->ReceiveThread, drvCharReceiveLoop, (void *)pData, 0, RTTHREADTYPE_IO, RTTHREADFLAGS_WAITABLE, "CharRecv");
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync return PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, N_("Char#%d cannot create receive thread"), pDrvIns->iInstance);
c18940aaee473ca75acc33491c1dc77b3e8094e0vboxsync rc = RTThreadCreate(&pData->SendThread, drvCharSendLoop, (void *)pData, 0, RTTHREADTYPE_IO, RTTHREADFLAGS_WAITABLE, "CharSend");
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync return PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, N_("Char#%d cannot create send thread"), pDrvIns->iInstance);
fe96bc0e43d9c137304462ef8c2d79cbff22446fvboxsync PDMDrvHlpSTAMRegisterF(pDrvIns, &pData->StatBytesWritten, STAMTYPE_COUNTER, STAMVISIBILITY_USED, STAMUNIT_BYTES, "Nr of bytes written", "/Devices/Char%d/Written", pDrvIns->iInstance);
5a2abb913df18ed4e588e179043708667f7bc1a1vboxsync PDMDrvHlpSTAMRegisterF(pDrvIns, &pData->StatBytesRead, STAMTYPE_COUNTER, STAMVISIBILITY_USED, STAMUNIT_BYTES, "Nr of bytes read", "/Devices/Char%d/Read", pDrvIns->iInstance);
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Destruct a char driver instance.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Most VM resources are freed by the VM. This callback is provided so that
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * any non-VM resources can be freed correctly.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * @param pDrvIns The driver instance data.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsyncstatic DECLCALLBACK(void) drvCharDestruct(PPDMDRVINS pDrvIns)
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync LogFlow(("%s: iInstance=%d\n", __FUNCTION__, pDrvIns->iInstance));
97dc0e92bcc0cddf896cbf620b689b095c7346davboxsync LogRel(("Char%d: receive thread did not terminate\n", pDrvIns->iInstance));
914d33aebb63d8c288dfd1b7e74f8e2acf3eaa66vboxsync /* Empty the send queue */
97dc0e92bcc0cddf896cbf620b689b095c7346davboxsync LogRel(("Char%d: send thread did not terminate\n", pDrvIns->iInstance));
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Char driver registration record.
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* u32Version */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* szDriverName */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pszDescription */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync "Generic char driver.",
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* fFlags */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* fClass. */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* cMaxInstances */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* cbInstance */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnConstruct */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnDestruct */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnIOCtl */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnPowerOn */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnReset */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnSuspend */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnResume */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /* pfnDetach */
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync /** pfnPowerOff */