================ @@ -0,0 +1,107 @@ +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. + +There are currently 3 PRs up for upstreaming RPC: +- One that adds the ``lldb-rpc-gen`` tool and its common code: https://github.com/llvm/llvm-project/pull/138031 +- One that adds the RPC server-side interface code emitters: https://github.com/llvm/llvm-project/pull/138032 +- One that adds Python scripts to modify the LLDB private headers for use with RPC: https://github.com/llvm/llvm-project/pull/138028 + +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. + +Local variable storage +~~~~~~~~~~~~~~~~~~~~~~ + +First, variables are created to hold all arguments coming in from the client side. These variables will be a pointer for the SB API class in question, and corresponding variables for all parameters that the function has. Since this signature for ``SBDebugger::CreateTarget()`` only has one parameter, a ``const char *``, 2 local variables get created. A pointer for an ``SBDebugger`` object, and an ``RPCCommon::ConstCharPointer`` for the ``const char * filename`` parameter. The ``ConstCharPointer`` is a typedef over ``const char *`` in the main RPC core code. ---------------- bulbazord wrote:
Note: `ConstCharPointer` is not a typedef but a full-fledged class. It's backed by a `std::string` but has lots of convenience methods for operating at the RPC layer. 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
