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)
RpcDebugLibData * | RpcDebug_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:

- RPCs to be sent to the application: these are input to the application, and can be tied to a validation function to make sure the response from the application is correct.
- Validation functions for "outgoing" RPCs: these are functions called in response to RPCs initiated by the applications; they can be mapped to specific RPC command strings, to make writing the plugin easier.

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

typedef struct RpcDebugLibData 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

typedef struct RpcDebugMsgList RpcDebugMsgList

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

## RpcDebugMsgMapping

typedef struct RpcDebugMsgMapping 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

typedef struct RpcDebugPlugin 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

typedef struct RpcDebugRecvMapping 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] | ctx | The 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] | ctx | The application context.
  [in] | dbgPlugin | Path 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] | rpcdata | The injected RPC data.
  [in] | list | The 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] | str | The string to set.
  [out] | res | Where to store the result.
  [out] | len | Where to store the length.