================ @@ -0,0 +1,94 @@ +LLDB RPC Upstreaming Design Doc +=============================== + +This document aims to explain the general structure of the upstreaming patches for adding LLDB RPC. The 2 primary concepts explained here will be: + +* How LLDB RPC is used +* How the ``lldb-rpc-gen`` works and what it outputs + +LLDB RPC +********* + +LLDB RPC is a framework by which processes can communicate with LLDB out of process while maintaining compatibility with the SB API. More details are explained in the `RFC<https://discourse.llvm.org/t/rfc-upstreaming-lldb-rpc/85804>`_ for upstreaming LLDB RPC, but the main focus in this doc for this section will be how exactly the code is structured for the PRs that will upstream this code. + +The ``lldb-rpc-gen`` tool +************************* + +``lldb-rpc-gen`` is the tool that generates the main client and server interfaces for LLDB RPC. It is a ``ClangTool`` that reads all SB API header files and their functions and outputs the client/server interfaces and certain other pieces of code, such as RPC-specfic versions of Python bindings used for the test suite. There's 3 main components behind ``lldb-rpc-gen``: + +1. The ``lldb-rpc-gen`` tool itself, which contains the main driver that uses the ``ClangTool``. +2. The code that generates all interfaces, which we call "emitters". All generated code for the interfaces are in C++, so the server side has one emitter for its generated source code and another for its generated header code. The client side has the same. +3. All common code shared between all emitters, such as helper methods and information about exceptions to take when emitting. + +The `current PR<https://github.com/llvm/llvm-project/pull/136748>`_ up for upstreaming LLDB RPC upstreams a subset of the code used for the tool. It upstreams the ``lldb-rpc-gen`` tool and all code needed for the server side emitters. Here's an example of what ``lldb-rpc-gen`` will output for the server side interface: + +Input +----- + +We'll use ``SBDebugger::CreateTarget(const char *filename)`` as an example. ``lldb-rpc-gen`` will read this method from ``SBDebugger.h``. The output is as follows. + +Source Code Output +------------------ + +:: + + bool rpc_server::_ZN4lldb10SBDebugger12CreateTargetEPKc::HandleRPCCall(rpc_common::Connection &connection, RPCStream &send, RPCStream &response) { + // 1) Make local storage for incoming function arguments + lldb::SBDebugger *this_ptr = nullptr; + rpc_common::ConstCharPointer filename; + // 2) Decode all function arguments + this_ptr = RPCServerObjectDecoder<lldb::SBDebugger>(send, rpc_common::RPCPacket::ValueType::Argument); + if (!this_ptr) + return false; + if (!RPCValueDecoder(send, rpc_common::RPCPacket::ValueType::Argument, filename)) + return false; + // 3) Call the method and encode the return value + lldb::SBTarget && __result = this_ptr->CreateTarget(filename.c_str()); + RPCServerObjectEncoder(response, rpc_common::RPCPacket::ValueType::ReturnValue, std::move(__result)); + return true; + } + +Function signature +~~~~~~~~~~~~~~~~~~ + +All server-side source code functions have a function signature that take the format ``bool rpc_server::<mangled-function-name>::HandleRPCCall(rpc_common::Connection &connection, RPCStream &send, RPCStream &response)``. Here the ``connection`` is what's maintained between the client and server. The ``send`` variable is a byte stream that carries information sent from the client. ``response`` is also a byte stream that will be populated with the return value obtained from the call into the SB API function that will be sent back to the client. ---------------- chelcassanova wrote:
Since we have interfaces for all functions, we want to differentiate them in the event of overloaded functions, e.g. `SBDebugger::CreateTarget` has 2 signatures, so each signature gets registered on the server side as: - `bool rpc_server::_ZN4lldb10SBDebugger12CreateTargetEPKc::HandleRPCCall` - `bool rpc_server::_ZN4lldb10SBDebugger12CreateTargetEPKcS2_S2_bRNS_7SBErrorE::HandleRPCCall` https://github.com/llvm/llvm-project/pull/138612 _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
