Changeset 86327 in vbox for trunk/include/VBox

Timestamp:

Sep 28, 2020 4:20:50 PM (5 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

140613

Message:

Debugger: Allow for different I/O providers instead of only TCP

So far TCP was the only option to communicate remotely with the internal debugger, the other option
was to use the console from the GUI directly. This commit reworks basic I/O to allow for different
providers where TCP is just one option. The second one being introduced is an IPC provider using a local
socket or named pipe depending on the platform. This allows for Windows kernel debugging over a pipe
using the KD stub in VirtualBox and WinDbg running on the host (not tested yet).

Furthermore this commit allows multiple stubs to be listening for connections at the same time, so
one can have a GDB stub listening on one TCP port and the native VBox debugger listening on another one
or even using a different I/O provider. Only one session can be active at a time though, because sharing
debugger states is impossible. To configure this the following CFGM keys need to be set for each listener:

"DBGC/<Some unique ID>/Provider" "tcp|ipc"
"DBGC/<Some unique ID>/StubType" "native|gdb|kd"
"DBGC/<Some unique ID>/Address" "<ip>|<local named pipe or socket path>"
"DBGC/<Some unique ID>/Port" "<port>" (for TCP only)

File:

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

trunk/include/VBox/dbg.h

@@ -1103 +1103 @@
 
 
-
-/** Pointer to a DBGC backend. */
-typedef struct DBGCBACK *PDBGCBACK;
-
-/**
- * Checks if there is input.
- *
- * @returns true if there is input ready.
- * @returns false if there not input ready.
- * @param   pBack       Pointer to the backend structure supplied by
- *                      the backend. The backend can use this to find
- *                      it's instance data.
- * @param   cMillies    Number of milliseconds to wait on input data.
- */
-typedef DECLCALLBACKTYPE(bool, FNDBGCBACKINPUT,(PDBGCBACK pBack, uint32_t cMillies));
-/** Pointer to a FNDBGCBACKINPUT() callback. */
-typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT;
-
-/**
- * Read input.
- *
- * @returns VBox status code.
- * @param   pBack       Pointer to the backend structure supplied by
- *                      the backend. The backend can use this to find
- *                      it's instance data.
- * @param   pvBuf       Where to put the bytes we read.
- * @param   cbBuf       Maximum nymber of bytes to read.
- * @param   pcbRead     Where to store the number of bytes actually read.
- *                      If NULL the entire buffer must be filled for a
- *                      successful return.
- */
-typedef DECLCALLBACKTYPE(int, FNDBGCBACKREAD,(PDBGCBACK pBack, void *pvBuf, size_t cbBuf, size_t *pcbRead));
-/** Pointer to a FNDBGCBACKREAD() callback. */
-typedef FNDBGCBACKREAD *PFNDBGCBACKREAD;
-
-/**
- * Write (output).
- *
- * @returns VBox status code.
- * @param   pBack       Pointer to the backend structure supplied by
- *                      the backend. The backend can use this to find
- *                      it's instance data.
- * @param   pvBuf       What to write.
- * @param   cbBuf       Number of bytes to write.
- * @param   pcbWritten  Where to store the number of bytes actually written.
- *                      If NULL the entire buffer must be successfully written.
- */
-typedef DECLCALLBACKTYPE(int, FNDBGCBACKWRITE,(PDBGCBACK pBack, const void *pvBuf, size_t cbBuf, size_t *pcbWritten));
-/** Pointer to a FNDBGCBACKWRITE() callback. */
-typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
-
-/**
- * Ready / busy notification.
- *
- * @param   pBack       Pointer to the backend structure supplied by
- *                      the backend. The backend can use this to find
- *                      it's instance data.
- * @param   fReady      Whether it's ready (true) or busy (false).
- */
-typedef DECLCALLBACKTYPE(void, FNDBGCBACKSETREADY,(PDBGCBACK pBack, bool fReady));
-/** Pointer to a FNDBGCBACKSETREADY() callback. */
-typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY;
-
-
-/**
- * The communication backend provides the console with a number of callbacks
- * which can be used
- */
-typedef struct DBGCBACK
-{
-    /** Check for input. */
-    PFNDBGCBACKINPUT    pfnInput;
-    /** Read input. */
-    PFNDBGCBACKREAD     pfnRead;
-    /** Write output. */
-    PFNDBGCBACKWRITE    pfnWrite;
-    /** Ready / busy notification. */
-    PFNDBGCBACKSETREADY pfnSetReady;
-} DBGCBACK;
-
-DBGDECL(int)    DBGCCreate(PUVM pUVM, PDBGCBACK pBack, unsigned fFlags);
+/** Pointer to a const I/O callback table. */
+typedef const struct DBGCIO *PCDBGCIO;
+
+/**
+ * I/O callback table.
+ */
+typedef struct DBGCIO
+{
+    /**
+     * Destroys the given I/O instance.
+     *
+     * @returns nothing.
+     * @param   pDbgcIo     Pointer to the I/O structure supplied by the I/O provider.
+     */
+    DECLCALLBACKMEMBER(void, pfnDestroy, (PCDBGCIO pDbgcIo));
+
+    /**
+     * Wait for input available for reading.
+     *
+     * @returns Flag whether there is input ready upon return.
+     * @retval  true if there is input ready.
+     * @retval  false if there not input ready.
+     * @param   pDbgcIo     Pointer to the I/O structure supplied by
+     *                      the I/O provider. The backend can use this to find it's instance data.
+     * @param   cMillies    Number of milliseconds to wait on input data.
+     */
+    DECLCALLBACKMEMBER(bool, pfnInput, (PCDBGCIO pDbgcIo, uint32_t cMillies));
+
+    /**
+     * Read input.
+     *
+     * @returns VBox status code.
+     * @param   pDbgcIo     Pointer to the I/O structure supplied by
+     *                      the I/O provider. The backend can use this to find it's instance data.
+     * @param   pvBuf       Where to put the bytes we read.
+     * @param   cbBuf       Maximum nymber of bytes to read.
+     * @param   pcbRead     Where to store the number of bytes actually read.
+     *                      If NULL the entire buffer must be filled for a
+     *                      successful return.
+     */
+    DECLCALLBACKMEMBER(int, pfnRead, (PCDBGCIO pDbgcIo, void *pvBuf, size_t cbBuf, size_t *pcbRead));
+
+    /**
+     * Write (output).
+     *
+     * @returns VBox status code.
+     * @param   pDbgcIo     Pointer to the I/O structure supplied by
+     *                      the I/O provider. The backend can use this to find it's instance data.
+     * @param   pvBuf       What to write.
+     * @param   cbBuf       Number of bytes to write.
+     * @param   pcbWritten  Where to store the number of bytes actually written.
+     *                      If NULL the entire buffer must be successfully written.
+     */
+    DECLCALLBACKMEMBER(int, pfnWrite, (PCDBGCIO pDbgcIo, const void *pvBuf, size_t cbBuf, size_t *pcbWritten));
+
+    /**
+     * Ready / busy notification.
+     *
+     * @returns nothing.
+     * @param   pDbgcIo     Pointer to the I/O structure supplied by
+     *                      the I/O provider. The backend can use this to find it's instance data.
+     * @param   fReady      Whether it's ready (true) or busy (false).
+     */
+    DECLCALLBACKMEMBER(void, pfnSetReady, (PCDBGCIO pDbgcIo, bool fReady));
+
+} DBGCIO;
+/** Pointer to an I/O callback table. */
+typedef DBGCIO *PDBGCIO;
+
+
+DBGDECL(int)    DBGCCreate(PUVM pUVM, PCDBGCIO pIo, unsigned fFlags);
 DBGDECL(int)    DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
 DBGDECL(int)    DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
-DBGDECL(int)    DBGCTcpCreate(PUVM pUVM, void **ppvUser);
-DBGDECL(int)    DBGCTcpTerminate(PUVM pUVM, void *pvData);
+
+DBGDECL(int)    DBGCIoCreate(PUVM pUVM, void **ppvData);
+DBGDECL(int)    DBGCIoTerminate(PUVM pUVM, void *pvData);
 
 /** @} */