SDK documentation

Disclaimer

Everything I document here is what it should work like. My code is not perfect, so if you're stuck with something, feel free to ping me.

Intro

Software Development Kit for the PulseDbg hypervisor is a package that allows you to work with a PulseDbg debuggee directly. Using the SDK you can implement a debugger, introspection tool, IDA shim - anything you like. The basic idea is the same - you have a target system running under the hypervisor, and a hypervisor client which is your application.

Overview

PulseSDK currently has the following directory layout:

• example - sample PulseClient application that demonstrates how to use PulseSDK. It also has a Pulse API interface loader sample which makes your life easy if you want to link the PulseEng library dynamically.
• include - header files necessary for the PulseEng library operation.
• x86/x64 - 32-bit and 64-bit PulseEng libraries that implement Pulse API.
• docs - an offline copy of the PulseSDK documentation. SDKMain.html is the current file.

PulseEng stands for Pulse Engine. It is a library that implements the communication layer with the PulseDbg hypervisor. It uses a custom binary protocol which is very boring. The protocol is not a secret, I just change it all the time. I do not promise backward or forward compatibility of the protocol. Use the current PulseEng version with the current PulseDbg host version in order to make sure that it works correctly.

PulseSDK also has a libpulseeng.so library compiled for Linux. I'm not a Linux guy, I'm still learning. I have no idea if it is compatible with your distro. All I can tell is I built it on my Ubuntu 24.04.

Header files

The main header for the SDK is "ps.h". Including this header is enough to use PulseSDK in your application. It includes the following headers:

• ps_status.h - pulse status codes. The main return type for SDK is PULSE_STATUS. It is somewhat like NTSTATUS and it also has a PULSE_SUCCESS macro to check if a status is considered to be successful. If you get a status which is not in this header file, please ping me.
• ps_event.h - pulse events. Describes the events that might be reported by the PulseDbg hypervisor.
• ps_transport.h - transport-related functions.
• ps_engine.h - engine related functions.
• ps_ctx.h - provides definitions for the register context.
• ps_api.h - Pulse API, the actual debugging / introspection functionality.
• ps_request_api.h - asynchronous variant of Pulse API.

Transport usage

The life cycle of a transport is:

• Create a transport instance choosing a transport type.
• If you don't know the interface, you can use TransportGetInterfaceCount and TransportGetInterfaceName functions.
• To initialize a transport interface you can use TransportSetInterfaceName OR TransportSetInterfaceIndex.
• By this time your transport instance is ready to be passed to the engine instance.
• TransportSetRawDataCallback is an option for you, don't bother to assign any if you don't need it.
• Kill the instance when it's not used anymore with TransportDestroy. It is better to shut down the engine instance first (and then the transport).

Engine usage

• As a prerequisite, create a transport instance. The engine will have nothing to work with without a transport, because it will have no means of communication with the target machine.
• Create an engine instance with EngCreateEngine.
• Assign an initialized transport to the engine instance with EngAssignTransport.
• Optionally you can override a value of request timeout for this engine instance using EngSetRequestTimeout.
• PsSetEventCallback is an option for you, don't bother to assign any if you don't need it.
• Start the engine with EngStart
• From now you can use Ps* functions and actually code something useful.
• If you need to change a transport or something, you can stop the engine execution with EngStop. You can also restart execution with EngStart.
• Use EngDestroyEngine when you no longer need an engine instance. It is better to shut down the engine instance first (and then the transport).

Engine requests

The way the debugging session works is there is a communication between a debugger and a debuggee via some transport. Transports have different properties (like maximum transfer unit or latency), which leads to inevitable delays when performing any debugging action. It is also true that transports can be somewhat unstable, so there is a built-in logic inside the engine about how to handle packet losses. The request timeout that you can set via EngSetRequestTimeout is a total timeout for your request. Still, if an engine thinks that there was a packet drop, it will issue several retransmission attempts. The retransmission will happen shortly, i.e. request timeout value divided by a number of maximum retransmission count. So, there is a balance between the wait length and a retransmission opportunity: if you set this timeout to a small value, it might happen that retransmission will never have a chance to receive a valid reply. Therefore, if you want to adjust this value, please play with it first and see how it behaves.

Pulse API

First of all, when the target is running, it has a certain polling rate (configurable with PulseConfig utility). So keep in mind that there will be a longer delay (or even timeout fails) when calling Ps* functions with a running target. It is not prohibited to call target command functions on a running target, but several calls (like setting a breakpoint) are not SMP-safe. Freezing the target execution guarantees SMP-safety and also gives you the shortest possible delay of a function call. Second, the hypervisor natively works with physical addresses, so you'll have to get used a little to this fact. I'd recommend reviewing x86 architecture basics.

Request API

Request API provides more control over the transport request lifecyclt. It echoes Pulse API functions. Request API operates with requests. The lifecycle of the request is the following:

• Create a request with the PsRequestCreate function. PS_REQUEST is an opaque request handle which is used in the request API.
• Call any request Pulse API variant using the request handle. The request is now bound to the chosen API and its parameters.
• PsRequestSubmit function submits the request for execution in the hypervisor.
• You may use the PsRequestWait function for a timed wait of the request completion. Alternatively, you can poll the completion status using the PsRequestGetStatus function.
• You may cancel or reuse the request with the PsRequestReset function.
• You can use PsRequestExecute for the synchronous execution. It is the same as if you were using a regular Pulse API call.
• When you no longer need the request object, you can destroy it with the PsRequestDestroy function.

Transport functions

Engine functions

Pulse API

Pulse request API