ref: c971f253270dbd2e421a9740d342136335ed3256
parent: 20614653e930f3c614732505de6ee8da0acae447
author: Sigrid Solveig Haflínudóttir <sigrid@ftrv.se>
date: Sun Mar 23 18:36:04 EDT 2025
lsd: reformat docstrings
--- a/src/plan9/lsd.sl
+++ b/src/plan9/lsd.sl
@@ -8,9 +8,9 @@
The text and data fields are both tables from syms to symbols."
text data)
(defstruct frame
- "A stack frame. Loc is the enclosing function symbol and instruction
- address of the frame. Retpc is the return instruction address.
- Sp is the stack pointer value. Locals are all the local symbols."
+ "A stack frame. Loc is the enclosing function symbol and instruction
+ address of the frame. Retpc is the return instruction address. Sp is
+ the stack pointer value. Locals are all the local symbols."
loc retpc sp locals)
(def coref NIL)
@@ -87,7 +87,7 @@
(io-pread f (reg-addr reg) (list (reg-size reg)))))
(def (symbol-read symbol . rest)
- "Reads the value from the core file at the symbol's address"
+ "Reads the value from the core file at the symbol's address."
:doc-group lsd
:doc-see sym-local
(unless coref (error "not attached to proc"))
@@ -137,9 +137,9 @@
Examples:
- `(bpset 'strcpy)` ; breakpoint on strcpy function.
- `(bpset (curPC))` ; breakpoint on current instruction.
- `(bpset \"/sys/src/cmd/cat.c:26\")` ; breakpoint on line 26."
+ (bpset 'strcpy) ; breakpoint on strcpy function.
+ (bpset (curPC)) ; breakpoint on current instruction.
+ (bpset \"/sys/src/cmd/cat.c:26\") ; breakpoint on line 26."
:doc-group lsd)
(doc-for (bpdel loc)
@@ -156,9 +156,9 @@
Examples:
- `(bpdel 'strcpy)` ; remove breakpoint on strcpy function.
- `(bpdel (curPC))` ; remove breakpoint on current instruction.
- `(bpdel \"/sys/src/cmd/cat.c:26\")` ; remove breakpoint on line 26."
+ (bpdel 'strcpy) ; remove breakpoint on strcpy function.
+ (bpdel (curPC)) ; remove breakpoint on current instruction.
+ (bpdel \"/sys/src/cmd/cat.c:26\") ; remove breakpoint on line 26."
:doc-group lsd)
(def (detach)
@@ -193,8 +193,8 @@
(def (curPC) (and (>= pid 0) (readreg PC)))
(def (step (n 1))
- "Step `n` assembly instructions. Return the next instruction
- address to be executed or `NIL` if the program has exited."
+ "Step `n` assembly instructions. Return the next instruction address
+ to be executed or `NIL` if the program has exited."
:doc-group lsd
(if (= n 0)
(curPC)
@@ -210,8 +210,8 @@
(step (1- n))))))
(def (cont (:print T))
- "Continue program execution. Return the next instruction
- address to be executed or `NIL` if the program has exited."
+ "Continue program execution. Return the next instruction address to be
+ executed or `NIL` if the program has exited."
:doc-group lsd
(when (has? bptbl (curPC)) (step))
(let {[note (startstop)]}@@ -245,10 +245,11 @@
(def (over)
"Step one line of source code, going over a function call, not in.
- BUGS
+ Bugs:
+
Stepping over a function call will remain on the same line
- whenever there is an assignment of the return value. You
- will have to step twice in that case."
+ whenever there is an assignment of the return value. You will
+ have to step twice in that case."
:doc-group lsd
(let {[f (car (_stk))]}(line)
@@ -257,12 +258,11 @@
(func))))
(def (asmlist (n 5) (addr (curPC)))
- "Return a list of the next `n` disassembled instructions starting at `addr`.
+ "Return a list of the next `n` disassembled instructions starting at
+ `addr`. Just like `(asm)` but returns a list instead of printing.
- Each element in the list has the form `(address . instr)` where `instr`
- is the disassembled instruction at the `address`.
-
- Examples: just like `(asm)` but returns a list instead of printing."
+ Each element in the list has the form `(address . instr)` where
+ `instr` is the disassembled instruction at the `address`."
:doc-group lsd
(if (<= n 0)
()
@@ -274,27 +274,27 @@
(cons (cons addr instr) (asmlist (1- n) (+ addr isize)))))))
(def (asm (n 5) (addr (curPC)))
- "Print the next `n` disassembled instructions at addr.
+ "Print the next `n` disassembled instructions at `addr`.
Examples:
- `(asm)` ; print out 5 from current program instruction.
- `(asm 10)` ; print out 10 from current program instruction.
- `(asm 3 (sym-addr 'strecpy))` ; 3 instructions from strecpy"
+ (asm) ; print out 5 from current program instruction.
+ (asm 10) ; print out 10 from current program instruction.
+ (asm 3 (sym-addr 'strecpy)) ; 3 instructions from strecpy"
:doc-group lsd
(for-each (λ (i) (princ (hex (car i)) "\t" (cdr i) "\n"))
(asmlist n addr)))
(def (src (addr (curPC)))
- "Return a string of the filename and line number corresponding
- to the instruction address."
+ "Return a string of the filename and line number corresponding to the
+ instruction address."
:doc-group lsd
(when addr (lsd-fileline addr)))
(def (Bsrc (addr (curPC)))
- "Send a plumb message of the filename and line number
- corresponding to the instruction address so that the
- source code can be viewed in your text editor."
+ "Send a plumb message of the filename and line number corresponding to
+ the instruction address so that the source code can be viewed in your
+ text editor."
(let {[s (src addr)][plumbf (file "/mnt/plumb/send" :write)]}
(io-write plumbf
@@ -306,29 +306,26 @@
(io-close plumbf)))
(def (B stepper)
- "Step forward using the stepper and then plumb the
- new line to your editor.
+ "Step forward using the stepper and then plumb the new line to your
+ editor.
Examples:
- `(B line)`; step one line and then see
- `(B cont)`; continue and then see where you stop"
+ (B line) ; step one line and then see
+ (B cont) ; continue and then see where you stop"
:doc-group lsd
(stepper)
(Bsrc))
(def (filepc f (line NIL))
- "Return the instruction address corresponding to a filename
- and line number. It is the inverse of (src addr).
+ "Return the instruction address corresponding to a filename and line
+ number. It is the inverse of `(src addr)`.
Examples:
- #;> (filepc \"/sys/src/cmd/cat.c:5\")
- 2097192
- #;> (filepc \"/sys/src/cmd/cat.c\" 5)
- 2097192
- #;> (src 2097192)
- \"/sys/src/cmd/cat.c:5\""
+ (filepc \"/sys/src/cmd/cat.c:5\") → 2097192
+ (filepc \"/sys/src/cmd/cat.c\" 5) → 2097192
+ (src 2097192) → \"/sys/src/cmd/cat.c:5\""
:doc-group lsd
(if line
(lsd-file2pc f line)
@@ -339,13 +336,12 @@
(lsd-file2pc (car s) line)))))
(def (sym-global s)
- "Return a symbol from the attached proc's symbol table or NIL.
- Input is a sym.
+ "Return a symbol from the attached proc's symbol table or `NIL`. Input
+ is a `sym`.
Examples:
- #;> (sym-global 'strecpy)
- #(symbol \"strecpy\" #\\T 2276784)"
+ (sym-global 'strecpy) → #(symbol \"strecpy\" #\\T 2276784)"
:doc-group lsd
(def (find tbl k) (and (has? tbl k) (get tbl k)))
(or (find (global-text globals) s)
@@ -352,16 +348,13 @@
(find (global-data globals) s)))
(def (sym-local s)
- "Return a local symbol from the attached proc's current stack
- frame or NIL.
- Input is a sym.
+ "Return a local symbol from the attached proc's current stack frame or
+ `NIL`. Input is a `sym`.
Examples:
- #;> (sym-local 'i)
- #(symbol \"i\" #\\a 140737488350940)
- #;> (symbol-read (sym-local 'argc) 's32)
- #s32(2)"
+ (sym-local 'i) → #(symbol \"i\" #\\a 140737488350940)
+ (symbol-read (sym-local 'argc) 's32) → #s32(2)"
:doc-group lsd
(let {[ss (str s)]}(find ss
@@ -369,8 +362,8 @@
:key symbol-name)))
(def (sym-addr s)
- "Return the address of a symbol from the attached proc's
- symbol table or NIL. Input is a sym."
+ "Return the address of a symbol from the attached proc's symbol table
+ or NIL. Input is a sym."
:doc-group lsd
(symbol-addr (sym-global s)))
@@ -385,13 +378,12 @@
(def (new . args)
"Start a new process for debugging.
- Args will be passed unparsed as the argument vector to
- the executable.
+ Args will be passed unparsed as the argument vector to the executable.
Examples:
- `(new)`; new process with no arguments
- `(new \"-v\" \"/sys/src/cmd/sl/slmain.c\")`; two arguments."
+ (new) ; new process with no arguments
+ (new \"-v\" \"/sys/src/cmd/sl/slmain.c\") ; two arguments."
:doc-group lsd
(let {[v (apply lsd-new args)]}(when proc-stdin (io-close proc-stdin))