8e496a172b2000333186e5c1be75a50f398ed830vboxsync * VirtualBox Support Driver - IDC Client Lib, Core.
b86449a980a005ad946212cde0ab940e13032a0bvboxsync * Copyright (C) 2008-2010 Oracle Corporation
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * available from http://www.virtualbox.org. This file is free software;
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * you can redistribute it and/or modify it under the terms of the GNU
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * General Public License (GPL) as published by the Free Software
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * The contents of this file may alternatively be used under the terms
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * of the Common Development and Distribution License Version 1.0
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * VirtualBox OSE distribution, in which case the provisions of the
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * CDDL are applicable instead of those of the GPL.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * You may elect to license modified versions of this file under the
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * terms and conditions of either the GPL or the CDDL or both.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync/*******************************************************************************
8e496a172b2000333186e5c1be75a50f398ed830vboxsync* Header Files *
8e496a172b2000333186e5c1be75a50f398ed830vboxsync*******************************************************************************/
8e496a172b2000333186e5c1be75a50f398ed830vboxsync/*******************************************************************************
8e496a172b2000333186e5c1be75a50f398ed830vboxsync* Global Variables *
8e496a172b2000333186e5c1be75a50f398ed830vboxsync*******************************************************************************/
8e496a172b2000333186e5c1be75a50f398ed830vboxsyncstatic PSUPDRVIDCHANDLE volatile g_pMainHandle = NULL;
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Opens the IDC interface of the support driver.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * This will perform basic version negotiations and fail if the
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * minimum requirements aren't met.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * @returns VBox status code.
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync * @param pHandle The handle structure (output).
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync * @param uReqVersion The requested version. Pass 0 for default.
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync * @param uMinVersion The minimum required version. Pass 0 for default.
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync * @param puSessionVersion Where to store the session version. Optional.
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync * @param puDriverVersion Where to store the session version. Optional.
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync * @param puDriverRevision Where to store the SVN revision of the driver. Optional.
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsyncSUPR0DECL(int) SUPR0IdcOpen(PSUPDRVIDCHANDLE pHandle, uint32_t uReqVersion, uint32_t uMinVersion,
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync uint32_t *puSessionVersion, uint32_t *puDriverVersion, uint32_t *puDriverRevision)
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Validate and set failure return values.
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync AssertPtrNullReturn(puSessionVersion, VERR_INVALID_POINTER);
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync AssertPtrNullReturn(puDriverVersion, VERR_INVALID_POINTER);
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync AssertPtrNullReturn(puDriverRevision, VERR_INVALID_POINTER);
8e496a172b2000333186e5c1be75a50f398ed830vboxsync AssertReturn(!uMinVersion || (uMinVersion & UINT32_C(0xffff0000)) == (SUPDRV_IDC_VERSION & UINT32_C(0xffff0000)), VERR_INVALID_PARAMETER);
8e496a172b2000333186e5c1be75a50f398ed830vboxsync AssertReturn(!uReqVersion || (uReqVersion & UINT32_C(0xffff0000)) == (SUPDRV_IDC_VERSION & UINT32_C(0xffff0000)), VERR_INVALID_PARAMETER);
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Handle default version input and enforce minimum requirements made
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * by this library.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * The clients will pass defaults (0), and only in the case that some
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * special API feature was just added will they set an actual version.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * So, this is the place where can easily enforce a minimum IDC version
78edef1df590edefed7cef91b6bcbf4d84f79947vboxsync * on bugs and similar. It corresponds a bit to what SUPR3Init is
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * responsible for.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync uDefaultMinVersion = SUPDRV_IDC_VERSION & UINT32_C(0xffff0000);
8e496a172b2000333186e5c1be75a50f398ed830vboxsync if (!uMinVersion || uMinVersion < uDefaultMinVersion)
8e496a172b2000333186e5c1be75a50f398ed830vboxsync if (!uReqVersion || uReqVersion < uDefaultMinVersion)
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Setup the connect request packet and call the OS specific function.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync Req.u.In.u32MagicCookie = SUPDRVIDCREQ_CONNECT_MAGIC_COOKIE;
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * We don't really trust anyone, make sure the returned
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * session and version values actually makes sense.
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync && (Req.u.Out.uSessionVersion & UINT32_C(0xffff0000)) == (SUPDRV_IDC_VERSION & UINT32_C(0xffff0000)))
c7ff622115966b69b482bd2896662e40d823b22fvboxsync ASMAtomicCmpXchgPtr(&g_pMainHandle, pHandle, NULL);
3a5d16e1911830b585d10278ea2cdbb408e261e6vboxsync AssertMsgFailed(("pSession=%p uSessionVersion=0x%x (r%u)\n", Req.u.Out.pSession, Req.u.Out.uSessionVersion, Req.u.Out.uDriverRevision));
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Closes a IDC connection established by SUPR0IdcOpen.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * @returns VBox status code.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * @param pHandle The IDC handle.
8e496a172b2000333186e5c1be75a50f398ed830vboxsyncSUPR0DECL(int) SUPR0IdcClose(PSUPDRVIDCHANDLE pHandle)
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Catch closed handles and check that the session is valid.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync AssertPtrReturn(pHandle->s.pSession, VERR_INVALID_HANDLE);
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Create the request and hand it to the OS specific code.
c7ff622115966b69b482bd2896662e40d823b22fvboxsync ASMAtomicCmpXchgPtr(&g_pMainHandle, NULL, pHandle);
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Get the SUPDRV session for the IDC connection.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * This is for use with SUPDRV and component APIs that requires a valid
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * session handle.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * @returns The session handle on success, NULL if the IDC handle is invalid.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * @param pHandle The IDC handle.
8e496a172b2000333186e5c1be75a50f398ed830vboxsyncSUPR0DECL(PSUPDRVSESSION) SUPR0IdcGetSession(PSUPDRVIDCHANDLE pHandle)
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * Looks up a IDC handle by session.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * @returns The IDC handle on success, NULL on failure.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * @param pSession The session to lookup.
8e496a172b2000333186e5c1be75a50f398ed830vboxsync * @internal
8e496a172b2000333186e5c1be75a50f398ed830vboxsyncPSUPDRVIDCHANDLE supR0IdcGetHandleFromSession(PSUPDRVSESSION pSession)