#!/usr/bin/env python
# ---------------------------------------------------------------------
# Be sure to add the python path that points to the LLDB shared library.
#
# # To use this in the embedded python interpreter using "lldb" just
# import it with the full path using the "command script import"
# command
# (lldb) command script import /path/to/cmdtemplate.py
# ---------------------------------------------------------------------
import inspect
import lldb
import argparse
import shlex
import sys
# Each new breakpoint gets a unique ID starting from 1.
nextid = 1
# List of breakpoint set from python, the key is the ID and the value the
# actual breakpoint. These are NOT LLDB SBBreakpoint objects.
breakpoints = dict()
exprOptions = lldb.SBExpressionOptions()
exprOptions.SetIgnoreBreakpoints()
exprOptions.SetLanguage(lldb.eLanguageTypeC)
class MlirDebug:
"""MLIR debugger commands
This is the class that hooks into LLDB and registers the `mlir` command.
Other providers can register subcommands below this one.
"""
lldb_command = "mlir"
parser = None
def __init__(self, debugger, unused):
super().__init__()
self.create_options()
self.help_string = MlirDebug.parser.format_help()
@classmethod
def create_options(cls):
if MlirDebug.parser:
return MlirDebug.parser
usage = "usage: %s [options]" % (cls.lldb_command)
description = "TODO."
# Pass add_help_option = False, since this keeps the command in line
# with lldb commands, and we wire up "help command" to work by
# providing the long & short help methods below.
MlirDebug.parser = argparse.ArgumentParser(
prog=cls.lldb_command, usage=usage, description=description, add_help=False
)
MlirDebug.subparsers = MlirDebug.parser.add_subparsers(dest="command")
return MlirDebug.parser
def get_short_help(self):
return "MLIR debugger commands"
def get_long_help(self):
return self.help_string
def __call__(self, debugger, command, exe_ctx, result):
# Use the Shell Lexer to properly parse up command options just like a
# shell would
command_args = shlex.split(command)
try:
args = MlirDebug.parser.parse_args(command_args)
except:
result.SetError("option parsing failed")
raise
args.func(args, debugger, command, exe_ctx, result)
@classmethod
def on_process_start(frame, bp_loc, dict):
print("Process started")
class SetControl:
# Define the subcommands that controls what to do when a breakpoint is hit.
# The key is the subcommand name, the value is a tuple of the command ID to
# pass to MLIR and the help string.
commands = {
"apply": (1, "Apply the current action and continue the execution"),
"skip": (2, "Skip the current action and continue the execution"),
"step": (3, "Step into the current action"),
"next": (4, "Step over the current action"),
"finish": (5, "Step out of the current action"),
}
@classmethod
def register_mlir_subparser(cls):
for cmd, (cmdInt, help) in cls.commands.items():
parser = MlirDebug.subparsers.add_parser(
cmd,
help=help,
)
parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
frame = exe_ctx.GetFrame()
if not frame.IsValid():
result.SetError("No valid frame (program not running?)")
return
cmdInt = cls.commands.get(options.command, None)
if not cmdInt:
result.SetError("Invalid command: %s" % (options.command))
return
result = frame.EvaluateExpression(
"((bool (*)(int))mlirDebuggerSetControl)(%d)" % (cmdInt[0]),
exprOptions,
)
if not result.error.Success():
print("Error setting up command: %s" % (result.error))
return
debugger.SetAsync(True)
result = exe_ctx.GetProcess().Continue()
debugger.SetAsync(False)
class PrintContext:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"context", help="Print the current context"
)
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
frame = exe_ctx.GetFrame()
if not frame.IsValid():
result.SetError("Can't print context without a valid frame")
return
result = frame.EvaluateExpression(
"((bool (*)())&mlirDebuggerPrintContext)()", exprOptions
)
if not result.error.Success():
print("Error printing context: %s" % (result.error))
return
class Backtrace:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"backtrace", aliases=["bt"], help="Print the current backtrace"
)
cls.parser.set_defaults(func=cls.process_options)
cls.parser.add_argument("--context", default=False, action="store_true")
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
frame = exe_ctx.GetFrame()
if not frame.IsValid():
result.SetError(
"Can't backtrace without a valid frame (program not running?)"
)
result = frame.EvaluateExpression(
"((bool(*)(bool))mlirDebuggerPrintActionBacktrace)(%d)" % (options.context),
exprOptions,
)
if not result.error.Success():
print("Error printing breakpoints: %s" % (result.error))
return
###############################################################################
# Cursor manipulation
###############################################################################
class PrintCursor:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"cursor-print", aliases=["cursor-p"], help="Print the current cursor"
)
cls.parser.add_argument(
"--print-region", "--regions", "-r", default=False, action="store_true"
)
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
frame = exe_ctx.GetFrame()
if not frame.IsValid():
result.SetError(
"Can't print cursor without a valid frame (program not running?)"
)
result = frame.EvaluateExpression(
"((bool(*)(bool))mlirDebuggerCursorPrint)(%d)" % (options.print_region),
exprOptions,
)
if not result.error.Success():
print("Error printing cursor: %s" % (result.error))
return
class SelectCursorFromContext:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"cursor-select-from-context",
aliases=["cursor-s"],
help="Select the cursor from the current context",
)
cls.parser.add_argument("index", type=int, help="Index in the context")
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
frame = exe_ctx.GetFrame()
if not frame.IsValid():
result.SetError(
"Can't manipulate cursor without a valid frame (program not running?)"
)
result = frame.EvaluateExpression(
"((bool(*)(int))mlirDebuggerCursorSelectIRUnitFromContext)(%d)"
% options.index,
exprOptions,
)
if not result.error.Success():
print("Error manipulating cursor: %s" % (result.error))
return
class CursorSelectParent:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"cursor-parent", aliases=["cursor-up"], help="Select the cursor parent"
)
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
frame = exe_ctx.GetFrame()
if not frame.IsValid():
result.SetError(
"Can't manipulate cursor without a valid frame (program not running?)"
)
result = frame.EvaluateExpression(
"((bool(*)())mlirDebuggerCursorSelectParentIRUnit)()",
exprOptions,
)
if not result.error.Success():
print("Error manipulating cursor: %s" % (result.error))
return
class SelectCursorChild:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"cursor-child", aliases=["cursor-c"], help="Select the nth child"
)
cls.parser.add_argument("index", type=int, help="Index of the child to select")
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
frame = exe_ctx.GetFrame()
if not frame.IsValid():
result.SetError(
"Can't manipulate cursor without a valid frame (program not running?)"
)
result = frame.EvaluateExpression(
"((bool(*)(int))mlirDebuggerCursorSelectChildIRUnit)(%d)" % options.index,
exprOptions,
)
if not result.error.Success():
print("Error manipulating cursor: %s" % (result.error))
return
class CursorSelecPrevious:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"cursor-previous",
aliases=["cursor-prev"],
help="Select the cursor previous element",
)
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
frame = exe_ctx.GetFrame()
if not frame.IsValid():
result.SetError(
"Can't manipulate cursor without a valid frame (program not running?)"
)
result = frame.EvaluateExpression(
"((bool(*)())mlirDebuggerCursorSelectPreviousIRUnit)()",
exprOptions,
)
if not result.error.Success():
print("Error manipulating cursor: %s" % (result.error))
return
class CursorSelecNext:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"cursor-next", aliases=["cursor-n"], help="Select the cursor next element"
)
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
frame = exe_ctx.GetFrame()
if not frame.IsValid():
result.SetError(
"Can't manipulate cursor without a valid frame (program not running?)"
)
result = frame.EvaluateExpression(
"((bool(*)())mlirDebuggerCursorSelectNextIRUnit)()",
exprOptions,
)
if not result.error.Success():
print("Error manipulating cursor: %s" % (result.error))
return
###############################################################################
# Breakpoints
###############################################################################
class EnableBreakpoint:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"enable", help="Enable a single breakpoint (given its ID)"
)
cls.parser.add_argument("id", help="ID of the breakpoint to enable")
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
bp = breakpoints.get(int(options.id), None)
if not bp:
result.SetError("No breakpoint with ID %d" % int(options.id))
return
bp.enable(exe_ctx.GetFrame())
class DisableBreakpoint:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"disable", help="Disable a single breakpoint (given its ID)"
)
cls.parser.add_argument("id", help="ID of the breakpoint to disable")
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
bp = breakpoints.get(int(options.id), None)
if not bp:
result.SetError("No breakpoint with ID %s" % options.id)
return
bp.disable(exe_ctx.GetFrame())
class ListBreakpoints:
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
"list", help="List all current breakpoints"
)
cls.parser.set_defaults(func=cls.process_options)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
for id, bp in sorted(breakpoints.items()):
print(id, type(id), str(bp), "enabled" if bp.isEnabled else "disabled")
class Breakpoint:
def __init__(self):
global nextid
self.id = nextid
nextid += 1
breakpoints[self.id] = self
self.isEnabled = True
def enable(self, frame=None):
self.isEnabled = True
if not frame or not frame.IsValid():
return
# use a C cast to force the type of the breakpoint handle to be void * so
# that we don't rely on DWARF. Also add a fake bool return value otherwise
# LLDB can't signal any error with the expression evaluation (at least I don't know how).
cmd = (
"((bool (*)(void *))mlirDebuggerEnableBreakpoint)((void *)%s)" % self.handle
)
result = frame.EvaluateExpression(cmd, exprOptions)
if not result.error.Success():
print("Error enabling breakpoint: %s" % (result.error))
return
def disable(self, frame=None):
self.isEnabled = False
if not frame or not frame.IsValid():
return
# use a C cast to force the type of the breakpoint handle to be void * so
# that we don't rely on DWARF. Also add a fake bool return value otherwise
# LLDB can't signal any error with the expression evaluation (at least I don't know how).
cmd = (
"((bool (*)(void *)) mlirDebuggerDisableBreakpoint)((void *)%s)"
% self.handle
)
result = frame.EvaluateExpression(cmd, exprOptions)
if not result.error.Success():
print("Error disabling breakpoint: %s" % (result.error))
return
class TagBreakpoint(Breakpoint):
mlir_subcommand = "break-on-tag"
def __init__(self, tag):
super().__init__()
self.tag = tag
def __str__(self):
return "[%d] TagBreakpoint(%s)" % (self.id, self.tag)
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
cls.mlir_subcommand, help="add a breakpoint on actions' tag matching"
)
cls.parser.set_defaults(func=cls.process_options)
cls.parser.add_argument("tag", help="tag to match")
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
breakpoint = TagBreakpoint(options.tag)
print("Added breakpoint %s" % str(breakpoint))
frame = exe_ctx.GetFrame()
if frame.IsValid():
breakpoint.install(frame)
def install(self, frame):
result = frame.EvaluateExpression(
'((void *(*)(const char *))mlirDebuggerAddTagBreakpoint)("%s")'
% (self.tag),
exprOptions,
)
if not result.error.Success():
print("Error installing breakpoint: %s" % (result.error))
return
# Save the handle, this is necessary to implement enable/disable.
self.handle = result.GetValue()
class FileLineBreakpoint(Breakpoint):
mlir_subcommand = "break-on-file"
def __init__(self, file, line, col):
super().__init__()
self.file = file
self.line = line
self.col = col
def __str__(self):
return "[%d] FileLineBreakpoint(%s, %d, %d)" % (
self.id,
self.file,
self.line,
self.col,
)
@classmethod
def register_mlir_subparser(cls):
cls.parser = MlirDebug.subparsers.add_parser(
cls.mlir_subcommand,
help="add a breakpoint that filters on location of the IR affected by an action. The syntax is file:line:col where file and col are optional",
)
cls.parser.set_defaults(func=cls.process_options)
cls.parser.add_argument("location", type=str)
@classmethod
def process_options(cls, options, debugger, command, exe_ctx, result):
split_loc = options.location.split(":")
file = split_loc[0]
line = int(split_loc[1]) if len(split_loc) > 1 else -1
col = int(split_loc[2]) if len(split_loc) > 2 else -1
breakpoint = FileLineBreakpoint(file, line, col)
print("Added breakpoint %s" % str(breakpoint))
frame = exe_ctx.GetFrame()
if frame.IsValid():
breakpoint.install(frame)
def install(self, frame):
result = frame.EvaluateExpression(
'((void *(*)(const char *, int, int))mlirDebuggerAddFileLineColLocBreakpoint)("%s", %d, %d)'
% (self.file, self.line, self.col),
exprOptions,
)
if not result.error.Success():
print("Error installing breakpoint: %s" % (result.error))
return
# Save the handle, this is necessary to implement enable/disable.
self.handle = result.GetValue()
def on_start(frame, bpno, err):
print("MLIR debugger attaching...")
for _, bp in sorted(breakpoints.items()):
if bp.isEnabled:
print("Installing breakpoint %s" % (str(bp)))
bp.install(frame)
else:
print("Skipping disabled breakpoint %s" % (str(bp)))
return True
def __lldb_init_module(debugger, dict):
target = debugger.GetTargetAtIndex(0)
debugger.SetAsync(False)
if not target:
print("No target is loaded, please load a target before loading this script.")
return
if debugger.GetNumTargets() > 1:
print(
"Multiple targets (%s) loaded, attaching MLIR debugging to %s"
% (debugger.GetNumTargets(), target)
)
# Register all classes that have a register_lldb_command method
module_name = __name__
parser = MlirDebug.create_options()
MlirDebug.__doc__ = parser.format_help()
# Add the MLIR entry point to LLDB as a command.
command = "command script add -o -c %s.%s %s" % (
module_name,
MlirDebug.__name__,
MlirDebug.lldb_command,
)
debugger.HandleCommand(command)
main_bp = target.BreakpointCreateByName("main")
main_bp.SetScriptCallbackFunction("action_debugging.on_start")
main_bp.SetAutoContinue(auto_continue=True)
on_breackpoint = target.BreakpointCreateByName("mlirDebuggerBreakpointHook")
print(
'The "{0}" command has been installed for target `{1}`, type "help {0}" or "{0} '
'--help" for detailed help.'.format(MlirDebug.lldb_command, target)
)
for _name, cls in inspect.getmembers(sys.modules[module_name]):
if inspect.isclass(cls) and getattr(cls, "register_mlir_subparser", None):
cls.register_mlir_subparser()
Codebase Browser
llvm