REMOTE

Modules
	PLUGIN

Namespaces
namespace	remote
namespace	pinrt::rscschema

Classes
struct	remote::Rpc_buffer_wrapper
struct	RPC_message_schema
struct	RPC_arg

Macros
#define	IS_RPC_EXEC_ERROR(ret)   IS_PINOS_SYSCALL_ERROR(ret)
#define	RPCID_INVALID   (t_rpc_id)(0xFFFFFFFF)
#define	RPCID_MIN   (t_rpc_id)(2048)
#define	RPCID_MAX   (t_rpc_id)(RPCID_INVALID - 1025)
#define	RPCID_RESERVED_LOW_RANGE_START   (t_rpc_id)(0x00000000)
#define	RPCID_RESERVED_LOW_RANGE_END   (t_rpc_id)(RPCID_MIN - 1)
#define	RPCID_RESERVED_HIGH_RANGE_START   (t_rpc_id)(RPCID_MAX + 1)
#define	RPCID_RESERVED_HIGH_RANGE_END   (t_rpc_id)(RPCID_INVALID - 1)
#define	RPCID_IS_VALID(rpcId)   ((rpcId) >= RPCID_MIN && (rpcId) <= RPCID_MAX)
#define	RPCID_IS_RESERVED_LOW(rpcId)   ((rpcId) >= RPCID_RESERVED_LOW_RANGE_START && (rpcId) <= RPCID_RESERVED_LOW_RANGE_END)
#define	RPCID_IS_RESERVED_HIGH(rpcId)   ((rpcId) >= RPCID_RESERVED_HIGH_RANGE_START && (rpcId) <= RPCID_RESERVED_HIGH_RANGE_END)
#define	RPCID_IS_RESERVED(rpcId)   (RPCID_IS_RESERVED_LOW(rpcId) || RPCID_IS_RESERVED_HIGH(rpcId))
#define	RSC_RPC_MESSAGE_SCHEMA(rpcId, argCount, ...)
#define	MAKE_ARG_SCHEMA(rpcType, size)    (t_rpc_arg_schema)(((uint32_t)rpcType & 0x000000FFU) | (((uint32_t)size & 0x00001FFF) << 16))
#define	ARG_SCHEMA_TYPE(argSchema)   ((E_rpc_arg_type)(argSchema & 0x000000FFU))
#define	ARG_SCHEMA_SIZE(argSchema)   ((size_t)((argSchema >> 16) & 0x00001FFFU))
#define	MAX_RSC_RPC_SCHEMA_ARGS   32
#define	RSC_RPC_DATA_OFFSET   48

Typedefs
typedef enum E_rpc_arg_type	E_rpc_arg_type
typedef enum E_rpc_arg_flags	E_rpc_arg_flags
typedef uint32_t	t_rpc_id
typedef uint8_t	t_arg_count
typedef uint32_t	t_rpc_arg_schema
typedef struct RPC_message_schema	t_rpc_message_schema
typedef struct RPC_arg	t_rpc_arg

Enumerations
enum	E_pin_rpc_flags {   PinRpcFlagsNone ,   PinRpcFlagsNoResponseRequired ,   PinRpcFlagsCanBlockIndefinitely }
enum	E_rpc_arg_type {   RpcBoolean = 0 ,   RpcInt ,   RpcUInt ,   RpcChar ,   RpcFloat ,   RpcBuffer ,   RpcOOBRef ,   RpcRecord ,   RpcArray ,   RpcNil ,   RpcVoid = RpcNil ,   RpcPaddingNoEncode }
enum	E_rpc_arg_flags {   RpcArgFlagsNone = 0x0 ,   RpcArgFlagsDataEmpty = (1 << 0) }

Functions
t_syscall_ret	PIN_DoRPC (t_rpc_message_schema const *rpcSchema, t_rpc_arg *rpcArgs, E_pin_rpc_flags flags=PinRpcFlagsNone) noexcept
size_t	PIN_CalculateSafeRPCDataSize (t_rpc_message_schema const *rpcSchema) noexcept
Rpc_buffer_wrapper	remote::rpc_buffer (void *mem, size_t size, E_rpc_arg_flags flags=RpcArgFlagsNone) noexcept
Rpc_buffer_wrapper	remote::rpc_buffer (const void *mem, size_t size) noexcept
template<t_rpc_message_schema const & SCHEMA, typename RetType , E_pin_rpc_flags Flags = PinRpcFlagsNone, typename... Args>
pinrt::std::enable_if_t< details::Rpc_arg_type_traits< RetType >::is_void, bool >	remote::do_rpc (Args &&... args) noexcept
template<t_rpc_message_schema const & SCHEMA, typename RetType , E_pin_rpc_flags Flags = PinRpcFlagsNone, typename... Args>
pinrt::std::enable_if_t< !details::Rpc_arg_type_traits< RetType >::is_void, bool >	remote::do_rpc (RetType &retValue, Args &&... args) noexcept

Detailed Description

Remote Procedure Call APIs can be used by Pintools to execute RPCs implemented by a pind RPC plugin.

An example of using the remote APIs can be find in ManualExamples/buffer_offload.cpp

/*
 * Copyright (C) 2024-2025 Intel Corporation.
 * SPDX-License-Identifier: MIT
 */
 
#include <iostream>
#include <filesystem>
#include <cstdlib>
#include <cstddef>
#include <unistd.h>
#include "pin.H"
#include "buffer_offload.h"
 
/*
 * This pintool demonstrates Pin 4.x new RPC (Remote Procedure Call) mechanism which allows Pintools to offload
 * processing to a remote process.
 * This pintool collects information about memory accesses in a trace buffer, and when the buffer 
 * gets full transmits the buffer to a remote function for further processing.
 * The pintool is responsible for the instrumentation and data collection. The remote  function implemented as part of a
 * Pin server plugin (buffer_offload_plugin.cpp), is responsible for analyzing the collected data. The schema for the
 * RPC is shared between the Pintool and the plugin and is located in buffer_offload.h.
 */
 
// A knob for setting the name of the file into which the remote plugin will write the analysis report
KNOB< std::string > KnobOutputFile(KNOB_MODE_WRITEONCE, "pintool", "o", "memory_analysis.log", "output file");
 
// The id of the trace buffer assigned by Pin
BUFFER_ID buffeId = 0;
 
static bool open_out_file(const std::string& outFileName)
{
    bool fileOpened = false;
    return remote::do_rpc< OPEN_OUT_FILE_SCHEMA >(fileOpened, outFileName) && fileOpened;
}
static bool mem_analyze(VOID* buffer, uint32_t bufferSize)
{
    return remote::do_rpc< MEM_ANALYZE_SCHEMA, void >(remote::rpc_buffer(buffer, bufferSize));
}
static bool get_mem_access_info(ADDRINT& addrMin, ADDRINT& addrMax, unsigned& topRangesCount, MEMREF* topRanges)
{
    bool ret = false;
    if (remote::do_rpc< GET_MEM_ACCESS_INFO_SCHEMA >(
            ret, addrMin, addrMax, topRangesCount,
            remote::rpc_buffer(topRanges, topRangesCount * sizeof(MEMREF), RpcArgFlagsDataEmpty)))
    {
        return ret;
    }
    return false;
}
 
static void InitializeRemoteLogger()
{
    std::filesystem::path outfile = KnobOutputFile.Value();
    if (outfile.is_relative())
    {
        outfile = std::filesystem::current_path() / outfile;
    }
 
#if (TARGET_WINDOWS)
    // The Windows LSC implementation for ::getcwd (Source/pinrt/pinos/lsc/support/windows/syscallimp/getcwd.cpp)
    // prefixes the path with '/' - intentionally. However std::ofstream::open is not happy with the '/' so we remove it.
    std::string fullpath = outfile.string();
    if (0 == fullpath.find("/"))
    {
        outfile = fullpath.substr(1, fullpath.size() - 1);
    }
#endif
 
    std::cout << "Report will be written to " << outfile << std::endl;
    ASSERTX(open_out_file(outfile.string()));
}
 
/*
 * This function is called by Pin when the trace buffer gets full.
 * In this function we do not process the trace buffer but rather transmit it to the remote
 * plugin for further processing.
 */
static VOID* BufferFull(BUFFER_ID id, THREADID tid, const CONTEXT* ctxt, VOID* buffer, UINT64 numElements, VOID* v)
{
    ASSERTX(mem_analyze(buffer, numElements * sizeof(MEMREF)));
    return buffer;
}
 
VOID Fini(INT32 code, VOID* v)
{
    ADDRINT addrMin = 0, addrMax = 0;
    MEMREF topRanges[6] {};
    unsigned topRangesCount = sizeof(topRanges) / sizeof(MEMREF);
    ASSERTX(get_mem_access_info(addrMin, addrMax, topRangesCount, topRanges));
 
    std::cout << "Lowest address accessed 0x" << std::hex << addrMin << " ; Highest address accessed 0x" << std::hex << addrMax
              << std::endl;
    std::cout << "Largest " << topRangesCount << " ranges are:" << std::endl;
    for (unsigned i = 0; i < topRangesCount; ++i)
    {
        std::cout << '\t' << "Base: 0x" << std::hex << uintptr_t(topRanges[i].ea) << std::dec << " Size: " << topRanges[i].size
                  << " bytes" << std::endl;
    }
}
 
VOID Trace(TRACE trace, VOID* v)
{
    for (BBL bbl = TRACE_BblHead(trace); BBL_Valid(bbl); bbl = BBL_Next(bbl))
    {
        for (INS ins = BBL_InsHead(bbl); INS_Valid(ins); ins = INS_Next(ins))
        {
            UINT32 memoryOperands = INS_MemoryOperandCount(ins);
 
            for (UINT32 memOp = 0; memOp < memoryOperands; memOp++)
            {
                UINT32 numBytesAccessed = INS_MemoryOperandSize(ins, memOp);
                INS_InsertFillBuffer(ins,                                           // The application instruction
                                     IPOINT_BEFORE,                                 // before the instruction executes
                                     buffeId,                                       // The id of the buffer whose record is filled
                                     IARG_MEMORYOP_EA, memOp, offsetof(MEMREF, ea), // effective address
                                     IARG_UINT32, numBytesAccessed, offsetof(MEMREF, size), // number of bytes read/written
                                     IARG_END);
            }
        }
    }
}
 
INT32 Usage()
{
    std::cerr
        << "This tool demonstrates offloading analysis work to a remote process. "
        << "Instead of doing the processing in the analysis routine we send the data using an RPC message to the remote process"
        << std::endl;
    std::cerr << std::endl << KNOB_BASE::StringKnobSummary() << std::endl;
    return -1;
}
 
int main(int argc, char* argv[])
{
    if (PIN_Init(argc, argv))
    {
        return Usage();
    }
 
    // There is a physical limit for transmitting buffers to the remote process - 65535 bytes.
    // However we need to leave some room for RSC-RPC Message headers
    // We should limit the trace buffer size to not exceed that limit since we want to transmit the full buffer.
    const size_t bufferSizeLimit = PIN_CalculateSafeRPCDataSize(&MEM_ANALYZE_SCHEMA);
    const size_t pageSize        = getpagesize();
    ASSERTX(bufferSizeLimit >= pageSize);
    auto numPages = bufferSizeLimit / pageSize;
    buffeId       = PIN_DefineTraceBuffer(sizeof(MEMREF), numPages, BufferFull, 0);
 
    if (buffeId == BUFFER_ID_INVALID)
    {
        std::cerr << "Error: could not allocate initial buffer" << std::endl;
        return 1;
    }
 
    InitializeRemoteLogger();
    TRACE_AddInstrumentFunction(Trace, 0);
    PIN_AddFiniFunction(Fini, 0);
    PIN_StartProgram();
 
    return 0;
}

Macro Definition Documentation

IS_RPC_EXEC_ERROR

#define IS_RPC_EXEC_ERROR

(

ret

)

IS_PINOS_SYSCALL_ERROR(ret)

Check if ret is an error.

Client side interface to pind RPC plugins.

See Executing Remote Procedures section in Pin User Manual

Note

APIs declared in this file are under active development and are subject to change or removal without notice

This macro should be used to check if PIN_DoRPC() succeeded or not.

Note

The return status of PIN_DoRPC() does not indicate success or failure of the actual RPC (Remote Procedure Call). Just whether the RPC request was processed correctly by Pin & pind.

MAKE_ARG_SCHEMA

#define MAKE_ARG_SCHEMA	(		rpcType,
			size
	)		(t_rpc_arg_schema)(((uint32_t)rpcType & 0x000000FFU) | (((uint32_t)size & 0x00001FFF) << 16))

Helper macro for creating t_rpc_arg_schema.

Parameters

rpcType	The type of the argument (E_rpc_arg_type)
size	The size of the argument in bytes (for RpcRecord this is the number of members which can be at most 4096)

Note

This is a helper macro and it does not verify its inputs!

RPCID_INVALID

#define RPCID_INVALID   (t_rpc_id)(0xFFFFFFFF)

Indicates an Invalid RPC Id.

This RPC Id is used internally

RPCID_MAX

#define RPCID_MAX   (t_rpc_id)(RPCID_INVALID - 1025)

The largest valid RPC Id available for Pintool developers.

RPC Ids greater than RPCID_MAX are reserved for Pin

RPCID_MIN

#define RPCID_MIN   (t_rpc_id)(2048)

The smallest RPC Id available for Pintool developers.

RPC Ids less than RPCID_MIN are reserved for Pin

RSC_RPC_MESSAGE_SCHEMA

#define RSC_RPC_MESSAGE_SCHEMA	(		rpcId,
			argCount,
			...
	)

Value:

    {                                                \
        (rpcId), (argCount), ##__VA_ARGS__           \
    }

Helper macro for creating a t_rpc_message_schema.

Typedef Documentation

E_rpc_arg_type

typedef enum E_rpc_arg_type E_rpc_arg_type

The type of RSC RPC argument.

This is the type we wish to encode from/decode to not the type inside the RSC RPC Message. For instance RpcInt might be encoded as int4, int12, varint, int4_neg, int12_neg or varint_neg

Enumeration Type Documentation

E_pin_rpc_flags

enum E_pin_rpc_flags

RPC flags.

Note

These flags cannot be combined.

Enumerator
PinRpcFlagsNoResponseRequired	Normal operation. Will wait for a response with some "reasonable" internal timeout. If a timeout occurs the program will abort
PinRpcFlagsCanBlockIndefinitely	No response is expected from the server. Can return immediately

E_rpc_arg_flags

enum E_rpc_arg_flags

Bitwise flags affecting the encoding of RPC arguments.

Enumerator
RpcArgFlagsNone	Does not modify argument encoding behavior
RpcArgFlagsDataEmpty	Indicate that the argument has no encodable/decodable data If this value is set on encode then the argument will be encoded as RpcNil If this value is set returning from decode then the argument does not contain valid data.

E_rpc_arg_type

enum E_rpc_arg_type

The type of RSC RPC argument.

This is the type we wish to encode from/decode to not the type inside the RSC RPC Message. For instance RpcInt might be encoded as int4, int12, varint, int4_neg, int12_neg or varint_neg

Enumerator
RpcBoolean	Boolean argument type.
RpcInt	Integer (possibly negative) argument type.
RpcUInt	Unsigned integer argument type.
RpcChar	Character argument type (char, wchar_t, char16_t, char32_t)
RpcFloat	Floating point argument type (float, double, long double)
RpcBuffer	A memory buffer argument type.
RpcOOBRef	Currently not supported.
RpcRecord	A record argument type that may contain members of other types A record may contain upto 4096 members. Nested records are currently not supported
RpcArray	An array argument which may contain upto 4096 entries of the same type.
RpcNil	Indicates no data argument.
RpcVoid	The same as RpcNil.
RpcPaddingNoEncode	This type of argument is can be used to describe padding for a record argument. The decoder will use it when constructing the record layout in memory

Function Documentation

do_rpc() [1/2]

template<t_rpc_message_schema const & SCHEMA, typename RetType , E_pin_rpc_flags Flags = PinRpcFlagsNone, typename... Args>

pinrt::std::enable_if_t< details::Rpc_arg_type_traits< RetType >::is_void, bool > remote::do_rpc ( Args &&...  args )

inlinenoexcept

Execute an RPC (Remote Procedure Call).

This function is a convenience wrapper around PIN_DoRPC(). See PIN_DoRPC() for details.

Template Parameters

SCHEMA	The schema of the RPC to use. Since this is a template argument the schema must be fully initialized at compile time. Current implementation does not check the arguments against the schema at compile time. This may change in the future.
RetType	The type of the return value of the RPC - The type must be void for this overload. When using this overload the type is not automatically deduced and do_rpc() should be called as do_rpc<SCHEMA, void>(...).
Flags	Flags modifying the behavior of the RPC. If the value is set to PinRpcFlagsNoResponseRequired then no response is expected from the server. If the value is set to PinRpcFlagsCanBlockIndefinitely then the RPC can block indefinitely waiting for a response. If the value is set to PinRpcFlagsNone then the RPC will wait for a response with some "reasonable" internal timeout.
Args	Type of arguments - pack automatically deduced

Parameters

[in,out]

args

RPC arguments

Returns

bool True if the RPC request was sent, the server accepted & processed it and output arguments were successfully filled. If Flags is set to PinRpcFlagsNoResponseRequired then the return value is always true if the message was sent.

Note

This API is under active development and may change or be removed without notice.

Availability:

Mode: JIT & Probe
O/S: Linux, Windows*
CPU: IA-32 and Intel(R) 64 architectures

do_rpc() [2/2]

template<t_rpc_message_schema const & SCHEMA, typename RetType , E_pin_rpc_flags Flags = PinRpcFlagsNone, typename... Args>

pinrt::std::enable_if_t< !details::Rpc_arg_type_traits< RetType >::is_void, bool > remote::do_rpc ( RetType &  retValue, Args &&...  args  )

inlinenoexcept

Execute an RPC (Remote Procedure Call).

This function is a convenience wrapper around PIN_DoRPC(). See PIN_DoRPC() for details.

Template Parameters

SCHEMA	The schema of the RPC to use. Since this is a template argument the schema must be fully initialized at compile time. Current implementation does not check the arguments against the schema at compile time. This may change in the future.
RetType	The type of the return value of the RPC - automatically deduced If RetType is Rpc_buffer_wrapper then the size member must be 0 or big enough to hold the return value. Please not that if size is 0 then we assume the buffer contains enough space for the return value.
Flags	Flags modifying the behavior of the RPC. If the value is set to PinRpcFlagsCanBlockIndefinitely then the RPC can block indefinitely waiting for a response. If the value is set to PinRpcFlagsNone then the RPC will wait for a response with some "reasonable" internal timeout. PinRpcFlagsNoResponseRequired cannot be used with non-void return types RPCs.
Args	Type of arguments - pack automatically deduced

Parameters

[out]	retValue	An argument receiving the return value of the RPC
[in,out]	args	RPC arguments

Returns

True if the RPC request was sent, the server accepted & processed it and output arguments and return value were successfully filled.

Note

This API is under active development and may change or be removed without notice.

Availability:

Mode: JIT & Probe
O/S: Linux, Windows*
CPU: IA-32 and Intel(R) 64 architectures

PIN_CalculateSafeRPCDataSize()

size_t PIN_CalculateSafeRPCDataSize ( t_rpc_message_schema const *  rpcSchema )

inlinenoexcept

Calculate the size available for data given a message schema.

An RSC/RPC message can be of a maximum size of 64KB. However the actual size available for data in a message is 64KB - RSC_RPC_DATA_OFFSET - (size of argument encoding metadata). This function calculates the maximum possible size that the argument encoding metadata will take and returns a safe estimate to the size in bytes actually available for encoding.

Note

The size returned is for the data of all arguments passed to the RPC.

Parameters

[in]

rpcSchema

The message schema for which to calculate the metadata overhead

Returns

size_t - The available size for data given a schema.

Note

This API is under active development and may change or be removed without notice.

Availability:

Mode: JIT & Probe
O/S: Linux, Windows*
CPU: IA-32 and Intel(R) 64 architectures

PIN_DoRPC()

t_syscall_ret PIN_DoRPC ( t_rpc_message_schema const *  rpcSchema, t_rpc_arg *  rpcArgs, E_pin_rpc_flags  flags = PinRpcFlagsNone  )

inlinenoexcept

Execute an RPC (Remote Procedure Call).

The remote procedure is implemented by a plugin that is loaded by pind, the Pin server. The plugin must be installed prior starting pin with a Pintool that uses this function. For more information see Installing and Loading pind Plugins. If the plugin was not properly installed or loaded the call will fail. The return value of this function reflects the status of the remote execution. The return value of the remote function is written to the last arg in rpcArgs.

See Executing Remote Procedures section in Pin User Manual

Parameters

[in]	rpcSchema	The schema describing the remote procedure. Both the Pintool and the pind RPC plugin should use the same schema. The schema is used both to verify the arguments before calling the RPC, and is also used to verify the response to the RPC. The maximum arguments for an RPC schema accepted by this function is 15.
[in,out]	rpcArgs	An array of args to pass to the remote procedure. The args may be [in], [out] or [inout] arguments. The length of the array must be equal to the count of the message arguments as described by rpcSchema + one entry for the return value of the RPC. So the length of this array must be at least 1, even if the return argument type is RpcVoid or RpcNil. The return value of the remote procedure is written to the last argument in the array. Arguments are checked against rpcSchema.
[in]	flags	Flags modifying the behavior of the RPC.

Returns

t_syscall_ret On success SYSRET(SUCCESS) (0) is returned. On error a negative value is returned. The value represents an error that is specified in pinsyscall.h. To properly check if the return value is an error, IS_RPC_EXEC_ERROR macro should be used.

Note

The return status of PIN_DoRPC() does not indicate success or failure of the actual RPC (Remote Procedure Call). Just whether the RPC request was processed correctly by Pin & pind. The actual success or failure of the remote procedure call should be deduced from the return value of the RPC, if such return value exists for the RPC. The actual interpretation of the return value of the RPC is user defined.

This API is under active development and may change or be removed without notice.

Availability:

Mode: JIT & Probe
O/S: Linux, Windows*
CPU: IA-32 and Intel(R) 64 architectures

rpc_buffer() [1/2]

Rpc_buffer_wrapper remote::rpc_buffer ( const void *  mem, size_t  size  )

inlinenoexcept

Wrap a buffer to be used as an argument to an RPC.

Parameters

[in]	mem	The buffer memory
[in]	size	The size of the buffer in bytes. If the size is 0 then no data is copied to the RPC request.

Returns

Rpc_buffer_wrapper structure wrapping the buffer

Note

This API is under active development and may change or be removed without notice.

Availability:

Mode: JIT & Probe
O/S: Linux, Windows*
CPU: IA-32 and Intel(R) 64 architectures

rpc_buffer() [2/2]

Rpc_buffer_wrapper remote::rpc_buffer ( void *  mem, size_t  size, E_rpc_arg_flags  flags = RpcArgFlagsNone  )

inlinenoexcept

Wrap a buffer to be used as an argument to an RPC.

Parameters

[in,out]	mem	The buffer memory
[in]	size	The size of the buffer in bytes. If size is 0 then no data will be copied into the RPC request.
[in]	flags	Flags modifying the behaviour of the argument encoding. If this is set to E_rpc_arg_flags::RpcArgFlagsDataEmpty then no data will be sent to the RPC, however the RPC can fill the buffer on return. This behaviour is just a performance optimization so if the buffer is intended to be filled by the RPC and the contents are not valid until the RPC returns, then there is no point in copying the initial content to the RPC request.

Returns

Rpc_buffer_wrapper structure wrapping the buffer

Note

This API is under active development and may change or be removed without notice.

Availability:

Mode: JIT & Probe
O/S: Linux, Windows*
CPU: IA-32 and Intel(R) 64 architectures