Skip to content

Commit c4b28bf

Browse files
[lldb][Docs] Link from platform doc to extensions doc (#90029)
So we aren't describing the same packets twice. Basically turning the platform doc into a list of cross links. qLaunchSuccess was missing a description so I added one.
1 parent 22da5a6 commit c4b28bf

File tree

2 files changed

+265
-475
lines changed

2 files changed

+265
-475
lines changed

lldb/docs/resources/lldbgdbremote.md

Lines changed: 226 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,21 @@ The above packet helps when you have remote debugging abilities where you
130130
could launch a process on a remote host, this isn't needed for bare board
131131
debugging.
132132

133+
## qLaunchSuccess
134+
135+
### Brief
136+
137+
Check whether launching a process with the `A` packet succeeded.
138+
139+
### Description
140+
141+
Returns the status of the last attempt to launch a process.
142+
Either `OK` if no error ocurred, or `E` followed by a string
143+
describing the error.
144+
145+
### Priority To Implement
146+
147+
High, launching processes is a key part of LLDB's platform mode.
133148

134149
## QEnvironment:NAME=VALUE
135150

@@ -263,6 +278,20 @@ QSetWorkingDir:<ascii-hex-path>
263278
```
264279
This packet must be sent _prior_ to sending a "A" packet.
265280

281+
## qGetWorkingDir
282+
283+
### Brief
284+
285+
Get the current working directory of the platform stub in
286+
ASCII hex encoding.
287+
288+
### Example
289+
290+
```
291+
receive: qGetWorkingDir
292+
send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773
293+
```
294+
266295
## QSetDisableASLR:\<bool\>
267296

268297
### Brief
@@ -1029,13 +1058,17 @@ a remote host.
10291058
10301059
Request: `qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path>`
10311060
1061+
The request packet has the fields:
1062+
1. mode bits in base 16
1063+
2. file path in ascii-hex encoding
1064+
10321065
Reply:
10331066
* `F<mkdir-return-code>`
10341067
(mkdir called successfully and returned with the given return code)
10351068
* `Exx` (An error occurred)
10361069
10371070
1038-
## qPlatform_chmod
1071+
## vFile:chmod / qPlatform_chmod
10391072
10401073
### Brief
10411074
@@ -1900,6 +1933,43 @@ send packet: $qsProcessInfo#00
19001933
read packet: $E04#00
19011934
```
19021935
1936+
## qPathComplete (Platform Extension)
1937+
1938+
### Brief
1939+
1940+
Get a list of matched disk files/directories by passing a boolean flag
1941+
and a partial path.
1942+
1943+
### Example
1944+
1945+
```
1946+
receive: qPathComplete:0,6d61696e
1947+
send: M6d61696e2e637070
1948+
receive: qPathComplete:1,746573
1949+
send: M746573742f,74657374732f
1950+
```
1951+
1952+
If the first argument is zero, the result should contain all
1953+
files (including directories) starting with the given path. If the
1954+
argument is one, the result should contain only directories.
1955+
1956+
The result should be a comma-separated list of hex-encoded paths.
1957+
Paths denoting a directory should end with a directory separator (`/` or `\`.
1958+
1959+
## qKillSpawnedProcess (Platform Extension)
1960+
1961+
### Brief
1962+
1963+
Kill a process running on the target system.
1964+
1965+
### Example
1966+
1967+
```
1968+
receive: qKillSpawnedProcess:1337
1969+
send: OK
1970+
```
1971+
The request packet has the process ID in base 10.
1972+
19031973
## qLaunchGDBServer (Platform Extension)
19041974
19051975
### Brief
@@ -2397,3 +2467,158 @@ STUB REPLIES: {"process_state_value":48,"process_state string":"dyld_process_sta
23972467
Low. This packet is needed to prevent lldb's utility functions for
23982468
scanning the Objective-C class list from running very early in
23992469
process startup.
2470+
2471+
## vFile Packets
2472+
2473+
Though some of these may match the ones described in GDB's protocol
2474+
documentation, we include our own expectations here in case of
2475+
mismatches or extensions.
2476+
2477+
### vFile:size
2478+
2479+
#### Brief
2480+
2481+
Get the size of a file on the target system, filename in ASCII hex.
2482+
2483+
#### Example
2484+
2485+
```
2486+
receive: vFile:size:2f746d702f61
2487+
send: Fc008
2488+
```
2489+
2490+
response is `F` followed by the file size in base 16.
2491+
`F-1,errno` with the errno if an error occurs, base 16.
2492+
2493+
### vFile:mode
2494+
2495+
#### Brief
2496+
2497+
Get the mode bits of a file on the target system, filename in ASCII hex.
2498+
2499+
#### Example
2500+
2501+
```
2502+
receive: vFile:mode:2f746d702f61
2503+
send: F1ed
2504+
```
2505+
2506+
response is `F` followed by the mode bits in base 16, this `0x1ed` would
2507+
correspond to `0755` in octal.
2508+
`F-1,errno` with the errno if an error occurs, base 16.
2509+
2510+
### vFile:unlink
2511+
2512+
#### Brief
2513+
2514+
Remove a file on the target system.
2515+
2516+
#### Example
2517+
2518+
```
2519+
receive: vFile:unlink:2f746d702f61
2520+
send: F0
2521+
```
2522+
2523+
Argument is a file path in ascii-hex encoding.
2524+
Response is `F` plus the return value of `unlink()`, base 16 encoding.
2525+
Return value may optionally be followed by a comma and the base16
2526+
value of errno if unlink failed.
2527+
2528+
### vFile:symlink
2529+
2530+
#### Brief
2531+
2532+
Create a symbolic link (symlink, soft-link) on the target system.
2533+
2534+
#### Example
2535+
2536+
```
2537+
receive: vFile:symlink:<SRC-FILE>,<DST-NAME>
2538+
send: F0,0
2539+
```
2540+
2541+
Argument file paths are in ascii-hex encoding.
2542+
Response is `F` plus the return value of `symlink()`, base 16 encoding,
2543+
optionally followed by the value of errno if it failed, also base 16.
2544+
2545+
### vFile:open
2546+
2547+
#### Brief
2548+
2549+
Open a file on the remote system and return the file descriptor of it.
2550+
2551+
#### Example
2552+
2553+
```
2554+
receive: vFile:open:2f746d702f61,00000001,00000180
2555+
send: F8
2556+
```
2557+
2558+
request packet has the fields:
2559+
1. ASCII hex encoded filename
2560+
2. Flags passed to the open call, base 16.
2561+
Note that these are not the `oflags` that `open(2)` takes, but
2562+
are the constant values in `enum OpenOptions` from LLDB's
2563+
[`File.h`](https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Host/File.h).
2564+
3. Mode bits, base 16
2565+
2566+
response is `F` followed by the opened file descriptor in base 16.
2567+
`F-1,errno` with the errno if an error occurs, base 16.
2568+
2569+
### vFile:close
2570+
2571+
#### Brief
2572+
2573+
Close a previously opened file descriptor.
2574+
2575+
#### Example
2576+
2577+
```
2578+
receive: vFile:close:7
2579+
send: F0
2580+
```
2581+
2582+
File descriptor is in base 16. `F-1,errno` with the errno if an error occurs,
2583+
errno is base 16.
2584+
2585+
### vFile:pread
2586+
2587+
#### Brief
2588+
2589+
Read data from an opened file descriptor.
2590+
2591+
#### Example
2592+
2593+
```
2594+
receive: vFile:pread:7,1024,0
2595+
send: F4;a'b\00
2596+
```
2597+
2598+
Request packet has the fields:
2599+
1. File descriptor, base 16
2600+
2. Number of bytes to be read, base 16
2601+
3. Offset into file to start from, base 16
2602+
2603+
Response is `F`, followed by the number of bytes read (base 16), a
2604+
semicolon, followed by the data in the binary-escaped-data encoding.
2605+
2606+
### vFile:pwrite
2607+
2608+
#### Brief
2609+
2610+
Write data to a previously opened file descriptor.
2611+
2612+
#### Example
2613+
2614+
```
2615+
receive: vFile:pwrite:8,0,\cf\fa\ed\fe\0c\00\00
2616+
send: F1024
2617+
```
2618+
2619+
Request packet has the fields:
2620+
1. File descriptor, base 16
2621+
2. Offset into file to start from, base 16
2622+
3. binary-escaped-data to be written
2623+
2624+
Response is `F`, followed by the number of bytes written (base 16).

0 commit comments

Comments
 (0)