Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.46.0

0.46.0 / src / std / debug.lucb

#==============================================================================================
#
#   debug - The in-program source debugger's runtime
#
#   DESCRIPTION:
#       The hooks a `--debug` build calls on entry, exit and at each statement, and the
#       breakpoint console that reads frames by their described layout.
#
#==============================================================================================

import c
import memory
extern func getenv(name: c.str) -> c.str?
extern func c_read as "read"(descriptor: i32, buffer: void*, count: usize) -> isize
extern func c_exit as "exit"(code: i32) -> never

## A frame as the compiler described it under `--debug`: the function's name and
## source, then `count` locals laid out after it, in this record's own layout.
struct Shape:
    var name: str
    var source: str
    var count: u64

struct Local:
    var name: str
    var kind: str
    var offset: u64
    var size: u64

struct Activation:
    var shape: Shape*?
    var frame: void*?
    var line: u32

struct Break:
    var file: str
    var line: u32

var activations: Activation[512]
var depth: usize
var checked: bool
var active: bool
var started: bool
var stepping: bool
var step_over: usize
var breaks: Break[32]
var break_count: usize
var names: u8[4096]
var names_used: usize
var line_bytes: u8[512]

## Called at every function entry and exit of a `--debug` build.
# mark: Debugger hooks ========================================================================

## Enter a described lexical scope for the in-program debugger.
pub func enter(shape: void*):
    if depth < activations.length:
        activations[depth] = Activation(shape = (Shape*)shape, frame = none, line = 0)
    depth += 1

## Pop the current activation from the debugger's shadow stack.
pub func leave():
    if depth > 0:
        depth -= 1

## Called before every statement: stop when a breakpoint, a step, or the start asks.
pub func at(shape: void*, line: u32, frame: void*):
    if not checked:
        checked = true
        active = getenv("LUCE_DEBUG") != none
    if not active or depth == 0 or depth > activations.length:
        return
    let top = depth - 1
    let s = (Shape*)shape
    activations[top] = Activation(shape = s, frame = frame, line = line)
    var stop = false
    if not started:
        started = true
        stop = true
    elif stepping:
        stop = true
    elif step_over > 0 and depth <= step_over:
        stop = true
    elif hits(s.source, line):
        stop = true
    if not stop:
        return
    stepping = false
    step_over = 0
    print(f"stopped at {s.source}:{line} in {s.name}")
    prompt(top)

func hits(file: str, line: u32) -> bool:
    var i: usize = 0
    while i < break_count:
        let b = breaks[i]
        if b.line == line and (b.file == file or ends_with(file, b.file)):
            return true
        i += 1
    return false

func ends_with(text: str, suffix: str) -> bool:
    if suffix.length > text.length:
        return false
    return (str)text.bytes[text.length - suffix.length..] == suffix

## Read commands until one lets the program run.
func prompt(top: usize):
    while true:
        let line = read_line() else return
        let command = first_word(line)
        let rest = trim((str)line.bytes[command.length..])
        if command == "r" or command == "run" or command == "c" or command == "continue":
            return
        if command == "s" or command == "step":
            stepping = true
            return
        if command == "n" or command == "next":
            step_over = depth
            return
        if command == "q" or command == "quit":
            print("quit")
            c_exit(0)
        if command == "b" or command == "break":
            add_break(rest)
        elif command == "p" or command == "print":
            show_named(top, rest)
        elif command == "locals":
            show_all(top)
        elif command == "bt" or command == "backtrace":
            backtrace()
        elif command.length == 0:
            continue
        else:
            print(f"unknown command `{command}`; commands: break FILE:LINE, run, step, next, print NAME, locals, backtrace, quit")

func add_break(spec: str):
    var colon: usize = spec.length
    var i = spec.length
    while i > 0:
        i -= 1
        if spec.bytes[i] == ':':
            colon = i
            break
    if colon == spec.length:
        print("break needs FILE:LINE")
        return
    let file = (str)spec.bytes[..<colon]
    let number = parse_line((str)spec.bytes[colon + 1..])
    if number == 0 or break_count == breaks.length or names_used + file.length > names.length:
        print("cannot set that breakpoint")
        return
    memory.copy(names[names_used..], file.bytes, file.length)
    let kept = (str)names[names_used..<names_used + file.length]
    names_used += file.length
    breaks[break_count] = Break(file = kept, line = number)
    break_count += 1
    print(f"breakpoint {break_count} at {file}:{number}")

func parse_line(text: str) -> u32:
    var value: u32 = 0
    for byte in text.bytes:
        if byte < '0' or byte > '9':
            return 0
        value = value * 10 + (u32)(byte - '0')
    return value

func backtrace():
    var i = depth
    var index: usize = 0
    while i > 0:
        i -= 1
        let a = activations[i]
        if let s = a.shape:
            print(f"#{index} {s.name} at {s.source}:{a.line}")
        index += 1

func show_all(top: usize):
    let a = activations[top]
    let s = a.shape else return
    var i: u64 = 0
    while i < s.count:
        show(local_of(s, i), a.frame)
        i += 1

func show_named(top: usize, name: str):
    let a = activations[top]
    let s = a.shape else return
    var i: u64 = 0
    while i < s.count:
        let described = local_of(s, i)
        if described.name == name:
            show(described, a.frame)
            return
        i += 1
    print(f"no local named `{name}`")

## The locals follow the shape, each `memory.size_of(Local)` bytes.
func local_of(s: Shape*, index: u64) -> Local*:
    let base = (usize)s + memory.size_of(Shape) + (usize)index * memory.size_of(Local)
    return (Local*)base

## A local's value read from the frame and shown by its type's spelling.
func show(described: Local*, frame: void*?):
    let f = frame else return
    let address = (void*)((usize)f - (usize)described.offset)
    let kind = described.kind
    if kind == "i64" or kind == "isize":
        print(f"{described.name}: {kind} = {memory.read[i64](address)}")
    elif kind == "i32":
        print(f"{described.name}: {kind} = {memory.read[i32](address)}")
    elif kind == "i16":
        print(f"{described.name}: {kind} = {memory.read[i16](address)}")
    elif kind == "i8":
        print(f"{described.name}: {kind} = {memory.read[i8](address)}")
    elif kind == "u64" or kind == "usize":
        print(f"{described.name}: {kind} = {memory.read[u64](address)}")
    elif kind == "u32" or kind == "char":
        print(f"{described.name}: {kind} = {memory.read[u32](address)}")
    elif kind == "u16":
        print(f"{described.name}: {kind} = {memory.read[u16](address)}")
    elif kind == "u8":
        print(f"{described.name}: {kind} = {memory.read[u8](address)}")
    elif kind == "bool":
        print(f"{described.name}: {kind} = {memory.read[bool](address)}")
    elif kind == "f64":
        print(f"{described.name}: {kind} = {memory.read[f64](address)}")
    elif kind == "f32":
        print(f"{described.name}: {kind} = {memory.read[f32](address)}")
    elif kind == "str":
        let text = memory.read[str](address)
        print(f"{described.name}: {kind} = \"{text}\"")
    elif kind == "c.str":
        let text = memory.read[c.str](address)
        print(f"{described.name}: {kind} = \"{(str)text}\"")
    elif ends_with(kind, "*") or ends_with(kind, "*?"):
        print(f"{described.name}: {kind} = 0x{memory.read[usize](address):x}")
    else:
        var shown: usize = (usize)described.size
        if shown > 32:
            shown = 32
        var text: u8[160]
        var used: usize = 0
        var i: usize = 0
        while i < shown:
            let byte = memory.read[u8]((void*)((usize)address + i))
            let digits = "0123456789abcdef".bytes
            text[used] = digits[(usize)(byte >> 4)]
            text[used + 1] = digits[(usize)(byte & 15)]
            text[used + 2] = ' '
            used += 3
            i += 1
        print(f"{described.name}: {kind} = {described.size} bytes {(str)text[..<used]}")

func first_word(line: str) -> str:
    var i: usize = 0
    while i < line.length and line.bytes[i] != ' ':
        i += 1
    return (str)line.bytes[..<i]

func trim(text: str) -> str:
    var start: usize = 0
    var end = text.length
    while start < end and text.bytes[start] == ' ':
        start += 1
    while end > start and (text.bytes[end - 1] == ' ' or text.bytes[end - 1] == '\r'):
        end -= 1
    return (str)text.bytes[start..<end]

## One line from standard input, without its newline; none at the end of input.
func read_line() -> str?:
    var used: usize = 0
    while used < line_bytes.length:
        var byte: u8[1]
        let n = c_read(0, &byte[0], 1)
        if n <= 0:
            if used == 0:
                return none
            break
        if byte[0] == '\n':
            break
        line_bytes[used] = byte[0]
        used += 1
    return (str)line_bytes[..<used]