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

[via lldb-commits]

Author: David Spickett
Date: 2026-06-10T10:17:46+01:00
New Revision: a4c8e3dd883cbaa61c75fef25bf496bb3bd3350a

URL: https://github.com/llvm/llvm-project/commit/a4c8e3dd883cbaa61c75fef25bf496bb3bd3350a
DIFF: https://github.com/llvm/llvm-project/commit/a4c8e3dd883cbaa61c75fef25bf496bb3bd3350a.diff

LOG: [lldb][docs] Document what a Platform is (#202332)

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.

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.

Added: 
    

Modified: 
    lldb/docs/resources/lldbplatformpackets.md
    lldb/docs/resources/overview.md

Removed: 
    


################################################################################
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..0521b5fbc9f8a 100644
--- a/lldb/docs/resources/overview.md
+++ b/lldb/docs/resources/overview.md
@@ -153,6 +153,32 @@ 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, a simulated environment, or another device connected to the host
+machine.
+
+`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 can include:
+
+- Providing details about the environment, such as operating system
+  version.
+- Moving files to and from the environment using various protocols. Often
+  
diff erent from the usual GDB remote protocol, for example SSH and rsync.
+- 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`.
+- Device discovery. For example mobile devices connected to a host machine.
+
 ## Utility
 
 This module contains the lowest layers of LLDB. A lot of these classes don't