[lldb][Docs] Remove more subtitles from packets doc

@llvm/pr-subscribers-lldb

Author: David Spickett (DavidSpickett)

Changes

This removes various subtitles or converts them to bold text so that the table of contents is less cluttered. This includes "Example", "Notes", "Priority To Implement" and "Response". --- Patch is 32.23 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/90443.diff 1 Files Affected: - (modified) lldb/docs/resources/lldbgdbremote.md (+146-274) ``````````diff diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md index a9fa2a432b7009..aaf903c9a5d13b 100644 --- a/lldb/docs/resources/lldbgdbremote.md +++ b/lldb/docs/resources/lldbgdbremote.md @@ -42,10 +42,8 @@ read packet: $OK#9a send packet: + ``` -### Priority To Implement - -High. Any GDB remote server that can implement this should if the -connection is reliable. This improves packet throughput and increases +**Priority To Implement:** High. Any GDB remote server that can implement this +should if the connection is reliable. This improves packet throughput and increases the performance of the connection. ## QSupported @@ -84,9 +82,7 @@ In the example above, three lldb extensions are shown: watchpoints, up to a pointer size, `sizeof(void*)`, a reasonable baseline assumption. -### Priority To Implement - -Optional. +**Priority To Implement:** Optional ## "A" - launch args packet @@ -111,10 +107,8 @@ The above packet helps when you have remote debugging abilities where you could launch a process on a remote host, this isn't needed for bare board debugging. -### Priority To Implement - -Low. Only needed if the remote target wants to launch a target after -making a connection to a GDB server that isn't already connected to +**Priority To Implement:** Low. Only needed if the remote target wants to launch +a target after making a connection to a GDB server that isn't already connected to an inferior process. ## qLaunchSuccess @@ -125,9 +119,8 @@ Returns the status of the last attempt to launch a process. Either `OK` if no error ocurred, or `E` followed by a string describing the error. -### Priority To Implement - -High, launching processes is a key part of LLDB's platform mode. +**Priority To Implement:** High, launching processes is a key part of LLDB's +platform mode. ## QEnvironment:NAME=VALUE @@ -150,10 +143,8 @@ read packet: $OK#00 ``` This packet can be sent one or more times _prior_ to sending a "A" packet. -### Priority To Implement - -Low. Only needed if the remote target wants to launch a target after -making a connection to a GDB server that isn't already connected to +**Priority To Implement:** Low. Only needed if the remote target wants to launch +a target after making a connection to a GDB server that isn't already connected to an inferior process. ## QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE) @@ -173,18 +164,23 @@ read packet: $OK#00 ``` This packet can be sent one or more times _prior_ to sending a "A" packet. -### Priority To Implement - -Low. Only needed if the remote target wants to launch a target after -making a connection to a GDB server that isn't already connected to +**Priority To Implement:** Low. Only needed if the remote target wants to launch +a target after making a connection to a GDB server that isn't already connected to an inferior process. ## QEnableErrorStrings This packet enables reporting of Error strings in remote packet replies from the server to client. If the server supports this -feature, it should send an OK response. The client can expect the -following error replies if this feature is enabled in the server: +feature, it should send an OK response. + +``` +send packet: $QEnableErrorStrings +read packet: $OK#00 +``` + +The client can expect the following error replies if this feature is enabled in +the server: ``` EXX;AAAAAAAAA ``` @@ -195,17 +191,8 @@ It must be noted that even if the client has enabled reporting strings in error replies, it must not expect error strings to all error replies. -### Priority To Implement - -Low. Only needed if the remote target wants to provide strings that -are human readable along with an error code. - -### Example - -``` -send packet: $QEnableErrorStrings -read packet: $OK#00 -``` +**Priority To Implement:** Low. Only needed if the remote target wants to +provide strings that are human readable along with an error code. ## QSetSTDIN:\ / QSetSTDOUT:\ / QSetSTDERR:\ @@ -221,13 +208,10 @@ QSetSTDERR: ``` These packets must be sent _prior_ to sending a "A" packet. -### Priority To Implement - -Low. Only needed if the remote target wants to launch a target after -making a connection to a GDB server that isn't already connected to +**Priority To Implement:** Low. Only needed if the remote target wants to launch +a target after making a connection to a GDB server that isn't already connected to an inferior process. - ## QSetWorkingDir:\ Set the working directory prior to sending an "A" packet. @@ -238,10 +222,8 @@ QSetWorkingDir: ``` This packet must be sent _prior_ to sending a "A" packet. -### Priority To Implement - -Low. Only needed if the remote target wants to launch a target after -making a connection to a GDB server that isn't already connected to +**Priority To Implement:** Low. Only needed if the remote target wants to launch +a target after making a connection to a GDB server that isn't already connected to an inferior process. ## qGetWorkingDir @@ -249,8 +231,6 @@ an inferior process. Get the current working directory of the platform stub in ASCII hex encoding. -### Example - ``` receive: qGetWorkingDir send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773 @@ -270,10 +250,8 @@ read packet: OK ``` This packet must be sent _prior_ to sending a "A" packet. -### Priority To Implement - -Low. Only needed if the remote target wants to launch a target after -making a connection to a GDB server that isn't already connected to +**Priority To Implement:** Low. Only needed if the remote target wants to launch +a target after making a connection to a GDB server that isn't already connected to an inferior process and if the target supports disabling ASLR (Address space layout randomization). @@ -283,26 +261,27 @@ Enable the `threads:` and `thread-pcs:` data in the question-mark packet ("T packet") responses when the stub reports that a program has stopped executing. -### Priority To Implement - -Performance. This is a performance benefit to lldb if the thread id's -and thread pc values are provided to lldb in the T stop packet -- if -they are not provided to lldb, lldb will likely need to send one to -two packets per thread to fetch the data at every private stop. - -### Example - ``` send packet: QListThreadsInStopReply read packet: OK ``` +**Priority To Implement:** Performance. This is a performance benefit to lldb +if the thread id's and thread pc values are provided to lldb in the T stop packet +-- if they are not provided to lldb, lldb will likely need to send one to +two packets per thread to fetch the data at every private stop. + ## jLLDBTraceSupported Get the processor tracing type supported by the gdb-server for the current inferior. Responses might be different depending on the architecture and capabilities of the underlying OS. +``` +send packet: jLLDBTraceSupported +read packet: {"name":, "description":}/E;AAAAAAAAA +``` + ### Output Schema ``` @@ -317,19 +296,10 @@ capabilities of the underlying OS. If no tracing technology is supported for the inferior, or no process is running, then an error message is returned. -### Note - -This packet is used by Trace plug-ins (see `lldb_private::Trace.h`) to +**Note:** This packet is used by Trace plug-ins (see `lldb_private::Trace.h`) to do live tracing. Specifically, the name of the plug-in should match the name of the tracing technology returned by this packet. -### Example - -``` -send packet: jLLDBTraceSupported -read packet: {"name":, "description":}/E;AAAAAAAAA -``` - ## jLLDBTraceStart Start tracing a process or its threads using a provided tracing technology. @@ -341,10 +311,20 @@ response is returned, or an error otherwise. This traces existing and future threads of the current process. An error is returned if the process is already being traced. +``` +send packet: jLLDBTraceStart:{"type":,...other params}] +read packet: OK/E;AAAAAAAAA +``` + ### Thread Tracing This traces specific threads. +``` +send packet: jLLDBTraceStart:{"type":,"tids":,...other params}] +read packet: OK/E;AAAAAAAAA +``` + ### Input Schema ``` @@ -360,8 +340,7 @@ This traces specific threads. } ``` -### Notes - +**Notes:** - If "tids" is not provided, then the operation is "process tracing", otherwise it's "thread tracing". - Each tracing technology can have different levels of support for "thread @@ -468,20 +447,6 @@ Notes: - If "thread tracing" is attempted on a thread already being traced with either "thread tracing" or "process tracing", it fails. -### Examples - -Process tracing: -``` -send packet: jLLDBTraceStart:{"type":,...other params}] -read packet: OK/E;AAAAAAAAA -``` - -Thread tracing: -``` -send packet: jLLDBTraceStart:{"type":,"tids":,...other params}] -read packet: OK/E;AAAAAAAAA -``` - ## jLLDBTraceStop Stop tracing a process or its threads using a provided tracing technology. @@ -493,11 +458,21 @@ response is returned, or an error otherwise. Stopping a process trace stops the active traces initiated with "thread tracing". +``` +send packet: jLLDBTraceStop:{"type":}] +read packet: OK/E;AAAAAAAAA +``` + ### Thread Trace Stopping This is a best effort request, which tries to stop as many traces as possible. +``` +send packet: jLLDBTraceStop:{"type":,"tids":}] +read packet: OK/E;AAAAAAAAA +``` + ### Input Schema The schema for the input is @@ -512,27 +487,12 @@ The schema for the input is } ``` -### Notes - -- If "tids" is not provided, then the operation is "process trace stopping". +**Note:** If `tids` is not provided, then the operation is "process trace stopping". ### Intel Pt Stopping a specific thread trace started with "process tracing" is allowed. -### Examples - -Process trace stopping: -``` -send packet: jLLDBTraceStop:{"type":}] -read packet: OK/E;AAAAAAAAA -``` -Thread trace stopping: -``` -send packet: jLLDBTraceStop:{"type":,"tids":}] -read packet: OK/E;AAAAAAAAA -``` - ## jLLDBTraceGetState Get the current state of the process and its threads being traced by @@ -540,6 +500,11 @@ a given trace technology. The response is a JSON object with custom information depending on the trace technology. In case of errors, an error message is returned. +``` +send packet: jLLDBTraceGetState:{"type":}] +read packet: {...object}/E;AAAAAAAAA +``` + ### Input Schema ``` @@ -594,10 +559,8 @@ error message is returned. } ``` -### Notes - - - "traceThreads" includes all thread traced by both "process tracing" and - "thread tracing". +**Note:** `tracedThreads` includes all threads traced by both "process tracing" +and "thread tracing". ### Intel Pt @@ -631,13 +594,6 @@ Additional attributes: } ``` -### Example - -``` -send packet: jLLDBTraceGetState:{"type":}] -read packet: {...object}/E;AAAAAAAAA -``` - ## jLLDBTraceGetBinaryData Get binary data given a trace technology and a data identifier. @@ -645,6 +601,11 @@ The input is specified as a JSON object and the response has the same format as the "binary memory read" (aka "x") packet. In case of failures, an error message is returned. +``` +send packet: jLLDBTraceGetBinaryData:{"type":,"kind":,"tid":,"offset":,"size":}] +read packet: /E;AAAAAAAAA +``` + ### Schema The schema for the input is: @@ -661,13 +622,6 @@ The schema for the input is: } ``` -### Example - -``` -send packet: jLLDBTraceGetBinaryData:{"type":,"kind":,"tid":,"offset":,"size":}] -read packet: /E;AAAAAAAAA -``` - ## qRegisterInfo\ Discover register information from the remote GDB server. @@ -937,16 +891,13 @@ The keys and values are detailed below: modifying the CPSR register can cause the r8 - r14 and cpsr value to change depending on if the mode has changed. -### Priority To Implement - -High. Any target that can self describe its registers, should do so. -This means if new registers are ever added to a remote target, they +**Priority To Implement:** High. Any target that can self describe its registers, +should do so. This means if new registers are ever added to a remote target, they will get picked up automatically, and allows registers to change depending on the actual CPU type that is used. -NB: `qRegisterInfo` is deprecated in favor of the standard gdb remote -serial protocol register description method, -`qXfer:features:read:target.xml`. +**Note:** `qRegisterInfo` is deprecated in favor of the standard gdb remote +serial protocol register description method, `qXfer:features:read:target.xml`. If `qXfer:features:read:target.xml` is supported, `qRegisterInfo` does not need to be implemented. The target.xml format is used by most gdb RSP stubs whereas `qRegisterInfo` was an lldb-only design. @@ -977,10 +928,7 @@ drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp -rw-r--r-- 1 username groupname 3190 Aug 12 16:46 Makefile ``` -### Priority To Implement - -High. This command allows LLDB clients to run arbitrary shell -commands on a remote host. +**Priority To Implement:** High ## qPlatform_mkdir @@ -997,10 +945,7 @@ Reply: (mkdir called successfully and returned with the given return code) * `Exx` (An error occurred) -### Priority To Implement - -Low. This command allows LLDB clients to create new directories on -a remote host. +**Priority To Implement:** Low ## vFile:chmod / qPlatform_chmod @@ -1013,9 +958,7 @@ Reply: (chmod called successfully and returned with the given return code) * `Exx` (An error occurred) -### Priority To Implement - -Low. +**Priority To Implement:** Low ## qHostInfo @@ -1066,10 +1009,8 @@ Key value pairs are one of: AArch64 can have different page table setups for low and high memory, and therefore a different number of bits used for addressing. -### Priority To Implement - -High. This packet is usually very easy to implement and can help -LLDB select the correct plug-ins for the job based on the target +**Priority To Implement:** High. This packet is usually very easy to implement +and can help LLDB select the correct plug-ins for the job based on the target triple information that is supplied. ## qGDBServerVersion @@ -1107,19 +1048,17 @@ Suggested key names: * `major_version`: major version number * `minor_version`: minor version number -### Priority To Implement - -High. This packet is usually very easy to implement and can help -LLDB to work around bugs in a server's implementation when they +**Priority To Implement:** High. This packet is usually very easy to implement +and can help LLDB to work around bugs in a server's implementation when they are found. ## qProcessInfo Get information about the process we are currently debugging. -### Priority To Implement +**Priority To Implement:** Medium -Medium. On systems which can launch multiple different architecture processes, +On systems which can launch multiple different architecture processes, the qHostInfo may not disambiguate sufficiently to know what kind of process is being debugged. @@ -1180,9 +1119,9 @@ send packet: $qShlibInfoAddr#00 read packet: $7fff5fc40040#00 ``` -### Priority To Implement +**Priority To Implement:** High -High if you have a dynamic loader plug-in in LLDB for your target +If you have a dynamic loader plug-in in LLDB for your target triple (see the "qHostInfo" packet) that can use this information. Many times address load randomization can make it hard to detect where the dynamic loader binary and data structures are located and @@ -1203,9 +1142,9 @@ remote packets love to think that there is only _one_ reason that _one_ thread stops at a time. This allows us to see why all threads stopped and allows us to implement better multi-threaded debugging support. -### Priority To Implement +**Priority To Implement:** High -High if you need to support multi-threaded or multi-core debugging. +If you need to support multi-threaded or multi-core debugging. Many times one thread will hit a breakpoint and while the debugger is in the process of suspending the other threads, other threads will also hit a breakpoint. This packet allows LLDB to know why all @@ -1254,9 +1193,9 @@ read packet: .... We also added support for allocating and deallocating memory. We use this to allocate memory so we can run JITed code. -### Priority To Implement +**Priority To Implement:** High -High. Adding a thread suffix allows us to read and write registers +Adding a thread suffix allows us to read and write registers more efficiently and stops us from having to select a thread with one packet and then read registers with a second packet. It also makes sure that no errors can occur where the debugger thinks it @@ -1289,12 +1228,9 @@ You request a size and give the permissions. This packet does NOT need to be implemented if you don't want to support running JITed code. The return value is just the address of the newly allocated memory as raw big endian hex bytes. -### Priority To Implement - -High if you want LLDB to be able to JIT code and run that code. JIT -code also needs data which is also allocated and tracked. - -Low if you don't support running JIT'ed code. +**Priority To Implement:** High if you want LLDB to be able to JIT code and run +that code. JIT code also needs data which is also allocated and tracked. Low if +you don't support running JIT'ed code. ## _m\ @@ -1306,12 +1242,9 @@ got back from a previous call to the allocate memory packet. It returns `OK` if the memory was successfully deallocated, or `EXX`" for an error, or an empty response if not supported. -### Priority To Implement - -High if you want LLDB to be able to JIT code and run that code. JIT -code also needs data which is also allocated and tracked. - -Low if you don't support running JIT'ed code. +**Priority To Implement:** High if you want LLDB to be able to JIT code and run +that code. JIT code also needs data which is also allocated and tracked. Low if +you don't support running JIT'ed code. ## qMemoryRegionInfo:\ @@ -1371,9 +1304,9 @@ For instance, with a macOS process which has nothing mapped in the first The lack of `permissions:` indicates that none of read/write/execute are valid for this region. -### Priority To Implement +**Priority To Implement:** Medium -Medium. This is nice to have, but it isn't necessary. It helps LLDB +This is nice to have, but it isn't necessary. It helps LLDB do stack unwinding when we branch into memory that isn't executable. If we can detect that the code we are stopped in isn't executable, then we can recover registers for stack frames above the current @@ -1446,8 +1379,7 @@ involves calling `thread_abort_safely(mach_port_t thread)` to ensure we get the correct registers for a thread in case it is currently having code run on its behalf in the kernel. -### Response - +The response is either: * `` - The save_id result is a non-zero unsigned integer value that can be passed back to the GDB server using a `QRestoreRegisterState` packet to restore the registers @@ -1455,11 +1387,9 @@ currently having code run on its behalf in the kernel. * `EXX` - or an error code in the form of `EXX` where `XX` is a hex error code. -### Priority To Implement - -Low, this is mostly a convenience packet to avoid having to send all -registers with a `g` packet. It should only be implemented if support -for the `QRestoreRegisterState` is added. +**Priority To Implement:** Low, this is mostly a convenience packet to avoid +having to send all registers with a `g` packet. It should only be implemented if +support for the `QRestoreRegisterState` is added. ## QRestoreRegisterState:\ / QRestoreRegisterState:\;thread:XXXX; @@ -1473,16 +1403,13 @@ completion of the `... [truncated] ``````````

llvm / llvm-project

[lldb][Docs] Remove more subtitles from packets doc #90443