open-vm-tools 12.1.0
Data Structures | Macros | Typedefs | Functions
Debugging Tools Plugins

Defines functions and interfaces for debugging Tools plugins. More...

Data Structures

struct  RpcDebugRecvMapping
 
struct  RpcDebugMsgMapping
 
struct  RpcDebugMsgList
 
struct  RpcDebugPlugin
 
struct  RpcDebugLibData
 

Macros

#define RPCDEBUG_ASSERT(test, retval)
 

Typedefs

typedef gboolean(* RpcDebugRecvFn) (char *data, size_t dataLen, char **result, size_t *resultLen)
 
typedef struct RpcDebugRecvMapping RpcDebugRecvMapping
 
typedef gboolean(* RpcDebugValidateFn) (RpcInData *data, gboolean ret)
 
typedef struct RpcDebugMsgMapping RpcDebugMsgMapping
 
typedef struct RpcDebugMsgList RpcDebugMsgList
 
typedef gboolean(* RpcDebugSendFn) (RpcDebugMsgMapping *rpcdata)
 
typedef void(* RpcDebugShutdownFn) (ToolsAppCtx *ctx, struct RpcDebugPlugin *plugin)
 
typedef struct RpcDebugPlugin RpcDebugPlugin
 
typedef RpcDebugPlugin *(* RpcDebugOnLoadFn) (ToolsAppCtx *ctx)
 
typedef struct RpcDebugLibData RpcDebugLibData
 
typedef RpcDebugLibData *(* RpcDebugInitializeFn) (ToolsAppCtx *, gchar *)
 

Functions

G_BEGIN_DECLS void RpcDebug_DecRef (ToolsAppCtx *ctx)
 
void RpcDebug_IncRef (void)
 
RpcDebugLibDataRpcDebug_Initialize (ToolsAppCtx *ctx, gchar *dbgPlugin)
 
gboolean RpcDebug_SendNext (RpcDebugMsgMapping *rpcdata, RpcDebugMsgList *list)
 
void RpcDebug_SetResult (const char *str, char **res, size_t *len)
 

Detailed Description

Defines functions and interfaces for debugging Tools plugins.

This module provides functions for writing "debug plugins" - plugins which provide functionality for driving the Tools Services when they're running in "debug mode". Debug plugins are dynamically loaded by providing specific command-line options to the Tools service process.

How debug plugins work

Currently, there's only support for GuestRPC-based debug plugins.

The debug library implements an RPC channel that can be driven by a debug plugin, according to information provided by the plugin at load time.

The debug plugin can provide two types of information:

For more details, check the RpcDebugPlugin data structure.

Plugins that depend on events that are not only responses to RPC messages (such as timer-based outgoing RPCs) should make sure they tell the library that it should not stop running by incrementing its ref count (see RpcDebug_IncRef()). When the test is complete, the code can then call RpcDebug_DecRef() and, when the ref count reaches zero, the main application loop will be stopped.

Macro Definition Documentation

◆ RPCDEBUG_ASSERT

#define RPCDEBUG_ASSERT (   test,
  retval 
)
Value:
do { \
CU_ASSERT(test); \
g_return_val_if_fail(test, retval); \
} while (0)

Shorthand macro to both call CU_ASSERT() and return from the function if the assertion fails. Note that this file doesn't include CUnit.h, so you'll need to include that header to use this macro.

Typedef Documentation

◆ RpcDebugInitializeFn

typedef RpcDebugLibData*(* RpcDebugInitializeFn) (ToolsAppCtx *, gchar *)

Signature of the library's initialization function.

◆ RpcDebugLibData

Describes the external interface of the library. An instance of this struct is returned by RpcDebug_Initialize() and can be used by applications using the library to use the debugging functionality.

◆ RpcDebugMsgList

Defines a (NULL-terminated) list of message / validator mappings.

◆ RpcDebugMsgMapping

Defines a mapping between a message and a "validate" function.

◆ RpcDebugOnLoadFn

typedef RpcDebugPlugin*(* RpcDebugOnLoadFn) (ToolsAppCtx *ctx)

Signature for the plugin's entry point. The function works in a similar way to the "ToolsOnLoad" function for regular plugins.

◆ RpcDebugPlugin

Registration data for debug plugins, should be returned by the plugin's entry point function.

◆ RpcDebugRecvFn

typedef gboolean(* RpcDebugRecvFn) (char *data, size_t dataLen, char **result, size_t *resultLen)

Signature for the plugin's "receive" function, to validate the data applications send using RpcChannel_Send.

◆ RpcDebugRecvMapping

Defines a mapping between a message and a "receive" function.

◆ RpcDebugSendFn

typedef gboolean(* RpcDebugSendFn) (RpcDebugMsgMapping *rpcdata)

Signature for the plugin's "send" function, which provides the data to be sent when the service tries to read from the RPC Channel.

The function should return FALSE if the service should finish the test (any data provided when this function returns FALSE is ignored).

◆ RpcDebugShutdownFn

typedef void(* RpcDebugShutdownFn) (ToolsAppCtx *ctx, struct RpcDebugPlugin *plugin)

Signature for the plugin's "shutdown" function.

◆ RpcDebugValidateFn

typedef gboolean(* RpcDebugValidateFn) (RpcInData *data, gboolean ret)

Signature for validation functions. Validation functions are called after an application has processed an "incoming" RPC, so that the plugin can validate the response.

Function Documentation

◆ RpcDebug_DecRef()

G_BEGIN_DECLS void RpcDebug_DecRef ( ToolsAppCtx ctx)

Decreases the internal ref count of the library. When the ref count reaches zero, this function will ask the application's main loop to stop running.

Parameters
[in]ctxThe application contexnt.

◆ RpcDebug_IncRef()

void RpcDebug_IncRef ( void  )

Increases the internal ref count of the library. Test code that needs the process to stay alive should call this function to ensure that.

◆ RpcDebug_Initialize()

RpcDebugLibData* RpcDebug_Initialize ( ToolsAppCtx ctx,
gchar *  dbgPlugin 
)

Initializes the debug library and loads the debug plugin at the given path. This function panics if something goes wrong.

Parameters
[in]ctxThe application context.
[in]dbgPluginPath to the debug plugin.
Returns
Structure containing the debug library's information.

◆ RpcDebug_SendNext()

gboolean RpcDebug_SendNext ( RpcDebugMsgMapping rpcdata,
RpcDebugMsgList list 
)

Places the next item on the given RPC message list into the given RPC data. Updates the current index of the list.

Parameters
[in]rpcdataThe injected RPC data.
[in]listThe message list.
Returns
TRUE if updated the RPC data, FALSE if reached the end of the list.

◆ RpcDebug_SetResult()

void RpcDebug_SetResult ( const char *  str,
char **  res,
size_t *  len 
)

Sets res / len when responding to an RPC.

Parameters
[in]strThe string to set.
[out]resWhere to store the result.
[out]lenWhere to store the length.