DrvChar.cpp revision 801238b286a80a5dd67ba56a1f26c0bc98a2a1ea
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)
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.
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. */
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync pThis->IChar.pfnSetParameters = drvCharSetParameters;
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync pThis->IChar.pfnSetModemLines = drvCharSetModemLines;
5b1d6bab9f4cf5dacf1883e7c4a40c84349f597fvboxsync * Get the ICharPort interface of the above driver/device.
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync pThis->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 */
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsync pThis->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);
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 * 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 */