[Lldb-commits] [lldb] [lldb][docs] Document what a Platform is (PR #202332)

[via lldb-commits]

llvmorg-github-actions[bot] wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-lldb

Author: David Spickett (DavidSpickett)

<details>
<summary>Changes</summary>

Fixes #<!-- -->201875.

In #<!-- -->201875 a user was understandably confused what a platform even is, and I had never had to explain it from the conceptual point of view either.

So I wrote a long explanation (https://github.com/llvm/llvm-project/issues/201875#issuecomment-4634087717) specific to what they were trying to do.

I don't think we need all that in the docs and we don't have a great place for it anyway.

So my alternative is:
* A high level explanation in the overview, to say what a platform does.
* A link from there to https://lldb.llvm.org/use/remote.html which has a practical example of using one.
* A note in the platform extensions doc that our platform mode is not related to gdb's extended remote.

It should be possible to locate all that from website search, and failing that, lldb experts will be able to find it and link to it in future discussions.

---
Full diff: https://github.com/llvm/llvm-project/pull/202332.diff


2 Files Affected:

- (modified) lldb/docs/resources/lldbplatformpackets.md (+7) 
- (modified) lldb/docs/resources/overview.md (+24) 


``````````diff
diff --git a/lldb/docs/resources/lldbplatformpackets.md b/lldb/docs/resources/lldbplatformpackets.md
index fea225528c9a5..ef37250962223 100644
--- a/lldb/docs/resources/lldbplatformpackets.md
+++ b/lldb/docs/resources/lldbplatformpackets.md
@@ -4,6 +4,13 @@ This is a list of the packets that an lldb platform server
 needs to implement for the lldb testsuite to be run on a remote
 target device/system.
 
+::{note}
+LLDB's platform server mode is not the same as GDB's "extended-remote" mode,
+though they do have similar goals. LLDB
+[does not support](https://github.com/llvm/llvm-project/issues/196936)
+"extended-remote" mode.
+:::
+
 These are almost all lldb extensions to the gdb-remote serial
 protocol. Many of the `vFile:` packets are also described in the "Host
 I/O Packets" detailed in the gdb-remote protocol documentation,
diff --git a/lldb/docs/resources/overview.md b/lldb/docs/resources/overview.md
index 129b99ff494f2..a94ffc05a89bc 100644
--- a/lldb/docs/resources/overview.md
+++ b/lldb/docs/resources/overview.md
@@ -153,6 +153,30 @@ Classes that are related to a debug target include:
 - ABI for function calling in process being debugged
 - Execution context batons
 
+## Platform
+
+Platform classes are spread around the codebase, with the base `Platform` class
+in `Target`. Platforms provide functionality for managing the execution
+environment of targets. This environment may be the host machine, a remote
+machine, or a simulated environment that the platform launches on behalf of the
+user.
+
+`lldb-server` includes a "platform mode" which is not a `Platform` in itself.
+This mode implements a protocol used by many `Platform`s that manage a remote
+environment. See {doc}`/use/remote` for an example of how the `Platform`s in
+LLDB work together with `lldb-server`'s "platform mode".
+
+`Platform` features include:
+
+- Providing details about the environent, such as operating system
+  version.
+- Moving files to and from the environment.
+- Finding processes in the environment.
+- Setting up new debug servers to debug existing or new processes in the
+  environment.
+- Connecting LLDB to these new debug servers. In other words, making them into
+  a `Target`.
+
 ## Utility
 
 This module contains the lowest layers of LLDB. A lot of these classes don't

``````````

</details>


https://github.com/llvm/llvm-project/pull/202332