[DRAFT][lldb] Upstream lldb-rpc-gen and LLDB RPC server-side emitters

This commit upstreams lldb-rpc-gen, a tool that emits the client and
server interfaces used for LLDB RPC. This is the initial commit in the
upstreaming process for LLDB RPC. lldb-rpc-gen is a ClangTool that reads
the LLDB SB API headers and uses their information to generate the
interfaces for RPC. This commit specifically adds the server-side
emitters for easier review. The client-side interface will be added in a
later commit.

RFC: https://discourse.llvm.org/t/rfc-upstreaming-lldb-rpc/85804

Author: chelcassanova

lldb/scripts/convert-lldb-header-to-rpc-header.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# Usage: convert-lldb-header-to-rpc-header.py <path/to/input-header.h> <path/to/output-header.h>
+# This scripts takes common LLDB headers (such as lldb-defines.h) and replaces references to LLDB
+# with those for RPC. This happens for:
+# - namespace definitions
+# - namespace usage
+# - version string macros
+# - ifdef/ifndef lines
+
+import argparse
+import os
+import re
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("input")
+    parser.add_argument("output")
+    args = parser.parse_args()
+    input_path = str(args.input)
+    output_path = str(args.output)
+    with open(input_path, "r") as input_file:
+        lines = input_file.readlines()
+
+    with open(output_path, "w") as output_file:
+        for line in lines:
+            # NOTE: We do not use lldb-forward.h or lldb-versioning.h in RPC, so remove
+            # all includes that are found for these files.
+            if re.match(
+                r'#include "lldb/lldb-forward|#include "lldb/lldb-versioning', line
+            ):
+                continue
+            # For lldb-rpc-defines.h, replace the ifndef LLDB_LLDB_ portion with LLDB_RPC_ as we're not
+            # using LLDB private definitions in RPC.
+            elif re.match(r".+LLDB_LLDB_", line):
+                output_file.write(re.sub(r"LLDB_LLDB_", r"LLDB_RPC_", line))
+            # Similarly to lldb-rpc-defines.h, replace the ifndef for LLDB_API in SBDefines.h to LLDB_RPC_API_ for the same reason.
+            elif re.match(r".+LLDB_API_", line):
+                output_file.write(re.sub(r"LLDB_API_", r"LLDB_RPC_API_", line))
+            # Replace the references for the macros that define the versioning strings in
+            # lldb-rpc-defines.h.
+            elif re.match(r".+LLDB_VERSION", line):
+                output_file.write(re.sub(r"LLDB_VERSION", r"LLDB_RPC_VERSION", line))
+            elif re.match(r".+LLDB_REVISION", line):
+                output_file.write(re.sub(r"LLDB_REVISION", r"LLDB_RPC_REVISION", line))
+            elif re.match(r".+LLDB_VERSION_STRING", line):
+                output_file.write(
+                    re.sub(r"LLDB_VERSION_STRING", r"LLDB_RPC_VERSION_STRING", line)
+                )
+            # For local #includes
+            elif re.match(r'#include "lldb/lldb-', line):
+                output_file.write(re.sub(r"lldb/lldb-", r"lldb-rpc-", line))
+            # Rename the lldb namespace definition to lldb-rpc.
+            elif re.match(r"namespace lldb", line):
+                output_file.write(re.sub(r"lldb", r"lldb_rpc", line))
+            # Rename namespace references
+            elif re.match(r".+lldb::", line):
+                output_file.write(re.sub(r"lldb::", r"lldb_rpc::", line))
+            else:
+                # Write any line that doesn't need to be converted
+                output_file.write(line)
+
+
+if __name__ == "__main__":
+    main()

lldb/scripts/framework-header-include-fix.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+# Usage: framework-header-include-fix.py <path/to/input-header.h> <path/to/output-header.h>
+# This script modifies all #include lines in all lldb-rpc headers
+# from either filesystem or local includes to liblldbrpc includes.
+
+import argparse
+import os
+import re
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("input")
+    parser.add_argument("output")
+    args = parser.parse_args()
+    input_path = str(args.input)
+    output_path = str(args.output)
+    with open(input_path, "r+") as input_file:
+        lines = input_file.readlines()
+
+    with open(output_path, "w+") as output_file:
+        for line in lines:
+            # Replace includes from RPCCommon to liblldbrpc includes.
+            # e.g. #include <lldb-rpc/common/RPCArgument.h> -> #include <LLDBRPC/RPCArgument.h>
+            if re.match(r".+<lldb-rpc/common", line):
+                output_file.write(re.sub(r"<lldb-rpc/common", r"<LLDBRPC", line))
+                # Replace all local file includes to liblldbrpc includes.
+                # e.g. #include "SBFoo.h" -> #include <LLDBRPC/SBFoo.h>
+            elif re.match(r'#include "(.*)"', line):
+                include_filename = re.search(r'#include "(.*)"', line).groups()[0]
+                output_file.write(
+                    re.sub(
+                        r'#include "(.*)"',
+                        r"#include <LLDBRPC/" + include_filename + ">",
+                        line,
+                    )
+                )
+            else:
+                # Write any line that doesn't need to be converted
+                output_file.write(line)
+
+
+if __name__ == "__main__":
+    main()

lldb/scripts/framework-header-version-fix.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# Usage: framework-header-version-fix.py <path/to/input-header.h> <path/to/output-header.h> MAJOR MINOR PATCH
+# This script modifies lldb-rpc-defines.h to uncomment the macro defines used for the LLDB
+# major, minor and patch values as well as populating their definitions.
+
+import argparse
+import os
+import re
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("input")
+    parser.add_argument("output")
+    parser.add_argument("lldb_version_major")
+    parser.add_argument("lldb_version_minor")
+    parser.add_argument("lldb_version_patch")
+    args = parser.parse_args()
+    input_path = str(args.input)
+    output_path = str(args.output)
+    lldb_version_major = args.lldb_version_major
+    lldb_version_minor = args.lldb_version_minor
+    lldb_version_patch = args.lldb_version_patch
+
+    with open(input_path, "r") as input_file:
+        lines = input_file.readlines()
+
+    with open(output_path, "w") as output_file:
+        for line in lines:
+            # Uncomment the line that defines the LLDB major version and populate its value.
+            if re.match(r"//#define LLDB_RPC_VERSION$", line):
+                output_file.write(
+                    re.sub(
+                        r"//#define LLDB_RPC_VERSION",
+                        r"#define LLDB_RPC_VERSION " + lldb_version_major,
+                        line,
+                    )
+                )
+            # Uncomment the line that defines the LLDB minor version and populate its value.
+            elif re.match(r"//#define LLDB_RPC_REVISION$", line):
+                output_file.write(
+                    re.sub(
+                        r"//#define LLDB_RPC_REVISION",
+                        r"#define LLDB_RPC_REVISION " + lldb_version_minor,
+                        line,
+                    )
+                )
+            # Uncomment the line that defines the complete LLDB version string and populate its value.
+            elif re.match(r"//#define LLDB_RPC_VERSION_STRING$", line):
+                output_file.write(
+                    re.sub(
+                        r"//#define LLDB_RPC_VERSION_STRING",
+                        r'#define LLDB_RPC_VERSION_STRING "{0}.{1}.{2}"'.format(
+                            lldb_version_major, lldb_version_minor, lldb_version_patch
+                        ),
+                        line,
+                    )
+                )
+            else:
+                # Write any line that doesn't need to be converted
+                output_file.write(line)
+
+
+if __name__ == "__main__":
+    main()

lldb/test/Shell/RPC/Generator/Inputs/CheckArrayPointer.h

@@ -0,0 +1,20 @@
+#ifndef LLDB_API_SBRPC_CHECKARRAYPTR_H
+#define LLDB_API_SBRPC_CHECKARRAYPTR_H
+
+#include <cstddef>
+#include <cstdio>
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+class LLDB_API SBRPC_CHECKARRAYPTR {
+public:
+  // Pointers to arrays followed by length must use a
+  // Bytes object constructed using that pointer and the sizeof()
+  // the array object.
+  int CheckArrayPtr(uint64_t *array, size_t array_len);
+
+}; // class SBRPC_CHECKARRAYPTR
+} // namespace lldb
+
+#endif // LLDB_API_SBRPC_CHECKARRAYPTR_H

lldb/test/Shell/RPC/Generator/Inputs/CheckConstCharPtrPtrWithLen.h

@@ -0,0 +1,19 @@
+#ifndef LLDB_API_SBRPC_CHECKCONSTCHARPTRPTRWITHLEN_H
+#define LLDB_API_SBRPC_CHECKCONSTCHARPTRPTRWITHLEN_H
+
+#include <cstddef>
+#include <cstdio>
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+class LLDB_API SBRPC_CHECKCONSTCHARPTRPTRWITHLEN {
+public:
+  // const char ** followed by len must use a StringList
+  // when being encoded.
+  int CheckConstCharPtrPtrWithLen(const char **arg1, size_t len);
+
+}; // class SBRPC_CHECKCONSTCHARPTRPTRWITHLEN
+} // namespace lldb
+
+#endif // LLDB_API_SBRPC_CHECKCONSTCHARPTRPTRWITHLEN_H

lldb/test/Shell/RPC/Generator/Inputs/CheckConstSBRef.h

@@ -0,0 +1,19 @@
+#ifndef LLDB_API_SBRPC_CHECKCONSTSBREF_H
+#define LLDB_API_SBRPC_CHECKCONSTSBREF_H
+
+#include <cstddef>
+#include <cstdio>
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+class LLDB_API SBRPC_CHECKCONSTSBREF {
+public:
+  // Const references to SB classes should be encoded as usual without
+  // needing to create a new object with its own connection.
+  int CheckConstSBRef(const SBDebugger &debugger_ref);
+
+}; // class SBRPC_CHECKCONSTSBREF
+} // namespace lldb
+
+#endif // LLDB_API_SBRPC_CHECKCONSTSBREF_H

lldb/test/Shell/RPC/Generator/Inputs/CheckNonConstSBRef.h

@@ -0,0 +1,20 @@
+#ifndef LLDB_API_SBRPC_CHECKNONCONSTSBREF_H
+#define LLDB_API_SBRPC_CHECKNONCONSTSBREF_H
+
+#include <cstddef>
+#include <cstdio>
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+class LLDB_API SBRPC_CHECKNONCONSTSBREF {
+public:
+  // Non-const references to SB classes will have new objects
+  // of that class constructed with the connection as the first parameter
+  // before being encoded if their existing connection is invalid.
+  int CheckNonConstSBRef(SBDebugger &debugger_ref);
+
+}; // class SBRPC_CHECKNONCONSTSBREF
+} // namespace lldb
+
+#endif // LLDB_API_SBRPC_CHECKNONCONSTSBREF_H

lldb/test/Shell/RPC/Generator/Inputs/CheckSBPointer.h

@@ -0,0 +1,21 @@
+#ifndef LLDB_API_SBRPC_CHECKSBPTR_H
+#define LLDB_API_SBRPC_CHECKSBPTR_H
+
+#include <cstddef>
+#include <cstdio>
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+class LLDB_API SBRPC_CHECKSBPTR {
+public:
+  // Pointers to SB objects must be checked to
+  // see if they're null. If so, then a new object of the given
+  // class must be created and encoded. Otherwise, the original
+  // parameter will be encoded.
+  int CheckSBPtr(SBDebugger *debugger_ptr);
+
+}; // class SBRPC_CHECKSBPTR
+} // namespace lldb
+
+#endif // LLDB_API_SBRPC_CHECKSBPTR_H

lldb/test/Shell/RPC/Generator/Inputs/CheckVoidPtr.h

@@ -0,0 +1,19 @@
+#ifndef LLDB_API_SBRPC_CHECKVOIDPTR_H
+#define LLDB_API_SBRPC_CHECKVOIDPTR_H
+
+#include <cstddef>
+#include <cstdio>
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+class LLDB_API SBRPC_CHECKVOIDPTR {
+public:
+  // void * followed by length must use a Bytes object
+  // when being encoded.
+  int CheckVoidPtr(void *buf, size_t len);
+
+}; // class SBRPC_CHECKVOIDPTR
+} // namespace lldb
+
+#endif // LLDB_API_SBRPC_CHECKVOIDPTR_H

lldb/test/Shell/RPC/Generator/Tests/Client/CheckArrayPointer.test

@@ -0,0 +1,13 @@
+// Skipping temporarily due to rdar://149500008
+# XFAIL: system-darwin
+# RUN: mkdir -p %t/server
+# RUN: mkdir -p %t/lib
+# RUN: %lldb-rpc-gen --output-dir=%t %S/../../Inputs/CheckArrayPointer.h
+
+# RUN: cat %t/lib/CheckArrayPointer.cpp | FileCheck %s
+
+// Pointers to arrays followed by length must use a
+// Bytes object constructed using that pointer and the sizeof()
+// the array object.
+# CHECK: lldb_rpc::SBRPC_CHECKARRAYPTR::CheckArrayPtr
+# CHECK: Bytes array_buffer(array, sizeof(uint64_t));