[Lldb-commits] [lldb] [DRAFT][lldb][RPC] Design doc for upstreaming PR (PR #138612)

[Chelsea Cassanova via lldb-commits]

================
@@ -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