Changeset 9695 in vbox for trunk/include/VBox/sup.h

Timestamp:

Jun 15, 2008 10:06:11 PM (16 years ago)

Author:

vboxsync

Message:

SUPDRV: Sketched out a component management interface and the generic bits of an IDC interface.

File:

• trunk/include/VBox/sup.h (modified) (1 diff)

trunk/include/VBox/sup.h

@@ -665 +665 @@
 SUPR0DECL(int) SUPR0Printf(const char *pszFormat, ...);
 
+/**
+ * Support driver component factory.
+ *
+ * Component factories are registered by drivers that provides services
+ * such as the host network interface filtering and access to the host
+ * TCP/IP stack.
+ *
+ * @remark Module dependencies and making sure that a component doesn't
+ *         get unloaded while in use, is the sole responsibility of the
+ *         driver/kext/whatever implementing the component.
+ */
+typedef struct SUPDRVFACTORY
+{
+    /** The (unique) name of the component factory. */
+    char szName[56];
+    /**
+     * Queries a factory interface.
+     *
+     * The factory interface is specific to each component and will be be
+     * found in the header(s) for the component alongside its UUID.
+     *
+     * @returns Pointer to the factory interfaces on success, NULL on failure.
+     *
+     * @param   pSession            The SUPDRV session making the query.
+     * @param   pSupDrvFactory      Pointer to this structure.
+     * @param   pInterfaceUuid      The UUID of the factory interface.
+     */
+    DECLR0CALLBACKMEMBER(void *, pfnQueryFactoryInterface,(PSUPDRVSESSION pSession, struct SUPDRVFACTORY *pSupDrvFactory, PCRTUUID pInterfaceUuid));
+} SUPDRVFACTORY;
+/** Pointer to a support driver factory. */
+typedef SUPDRVFACTORY *PSUPDRVFACTORY;
+
+/**
+ * Register a component factory with the support driver.
+ *
+ * @returns VBox status code.
+ * @param   pSession        The SUPDRV session (must be a ring-0 session).
+ * @param   pFactory        Pointer to the component factory registration structure.
+ *
+ * @remarks This interface is also available thru the IDC interfaces.
+ */
+SUPR0DECL(int) SUPR0ComponentRegisterFactory(PSUPDRVSESSION pSession, PSUPDRVFACTORY pFactory);
+
+/**
+ * Deregister a component factory.
+ *
+ * @returns VBox status code.
+ * @param   pSession        The SUPDRV session (must be a ring-0 session).
+ * @param   pFactory        Pointer to the component factory registration structure
+ *                          previously passed SUPR0ComponentRegisterFactory().
+ *
+ * @remarks This interface is also available thru the IDC interfaces.
+ */
+SUPR0DECL(int) SUPR0ComponentDeregisterFactory(PSUPDRVSESSION pSession, PSUPDRVFACTORY pFactory);
+
+/**
+ * Queries a component factory.
+ *
+ * @returns VBox status code.
+ * @retval  VBOX_SUPDRV_COMPONENT_NOT_FOUND if the component factory wasn't found.
+ * @retval  VBOX_SUPDRV_INTERFACE_NOT_SUPPORTED if the interface wasn't supported.
+ *
+ * @param   pSession        The SUPDRV session.
+ * @param   pszName         The name of the component factory.
+ * @param   pInterfaceUuid  The UUID of the factory interface.
+ * @param   ppvFactoryIf    Where to store the factory interface.
+ */
+SUPR0DECL(int) SUPR0ComponentQueryFactory(PSUPDRVSESSION pSession, const char *pszName, PCRTUUID pInterfaceUuid, void **ppvFactoryIf);
+
+
+/** @defgroup   grp_sup_r0_idc  The IDC Interface
+ * @ingroup grp_sup_r0
+ * @{
+ */
+
+/** The current SUPDRV IDC version.
+ * This follows the usual high word / low word rules, i.e. high word is the
+ * major number and it signifies incompatible interface changes. */
+#define SUPDRV_IDC_VERSION                  0x00010000
+
+/**
+ * The SUPDRV IDC entry point.
+ *
+ * (IDC = Inter-Driver Communication)
+ *
+ * @returns VBox status code.
+ *
+ * @param   pSession    The session. (This is NULL for SUPDRV_IDC_REQ_CONNECT.)
+ * @param   iReq        The request number.
+ * @param   pvReq       Pointer to the request packet. Optional for some requests.
+ * @param   cbReq       The size of the request packet.
+ */
+typedef DECLCALLBACK(int) FNSUPDRVIDCENTRY(PSUPDRVSESSION pSession, uint32_t iReq, void *pvReq, uint32_t cbReq);
+/** Pointer to the SUPDRV IDC entry point. */
+typedef FNSUPDRVIDCENTRY *PFNSUPDRVIDCENTRY;
+
+
+/**
+ * SUPDRV IDC: Connect request.
+ * This request takes a SUPDRVIDCREQCONNECT packet.
+ */
+#define SUPDRV_IDC_REQ_CONNECT                          UINT32_C(0xc0ffee01)
+/** A SUPDRV IDC connect request packet. */
+typedef union SUPDRVIDCREQCONNECT
+{
+    /** The input. */
+    struct SUPDRVIDCREQCONNECTIN
+    {
+        /** The magic cookie (SUPDRVIDCREQ_CONNECT_MAGIC). */
+        uint32_t        u32MagicCookie;
+        /** The desired version of the IDC interface. */
+        uint32_t        iReqVersion;
+        /** The minimum version of the IDC interface. */
+        uint32_t        iMinVersion;
+    } In;
+
+    /** The output. */
+    struct SUPDRVIDCREQCONNECTOUT
+    {
+        /** The support driver session. (An opaque.) */
+        PSUPDRVSESSION  pSession;
+        /** The version of the IDC interface for this session. */
+        uint32_t        iVersion;
+    } Out;
+} SUPDRVIDCREQCONNECT;
+/** Pointer to a SUPDRV IDC connect request. */
+typedef SUPDRVIDCREQCONNECT *PSUPDRVIDCREQCONNECT;
+/** Magic cookie value (SUPDRVIDCREQCONNECT::In.u32MagicCookie). ('tori') */
+#define SUPDRVIDCREQ_CONNECT_MAGIC_COOKIE               UINT32_C(0x69726f74)
+
+
+/**
+ * SUPDRV IDC: Disconnect request.
+ * This request does not take request packet.
+ */
+#define SUPDRV_IDC_REQ_DISCONNECT                       UINT32_C(0xc0ffee02)
+
+
+/**
+ * SUPDRV IDC: Disconnect request.
+ * This request takes a SUPDRVFACTORY packet.
+ */
+#define SUPDRV_IDC_REQ_COMPONENT_REGISTER_FACTORY       UINT32_C(0xc0ffee03)
+
+
+/**
+ * SUPDRV IDC: Dergister a component factory.
+ * This request takes a SUPDRVFACTORY packet.
+ */
+#define SUPDRV_IDC_REQ_COMPONENT_DEREGISTER_FACTORY     UINT32_C(0xc0ffee04)
+
+/** @} */
+
 /** @} */
 #endif