1*a1e26a70SApple OSS Distributions# Introduction 2*a1e26a70SApple OSS DistributionsXNU's LLDB macros are tools to aid debugging the kernel. 3*a1e26a70SApple OSS Distributions 4*a1e26a70SApple OSS DistributionsThere are several types of tests. 5*a1e26a70SApple OSS Distributions 6*a1e26a70SApple OSS Distributions# Types of tests and how to run them 7*a1e26a70SApple OSS Distributions## ScriptedProcess 8*a1e26a70SApple OSS DistributionsLLDB's ScriptedProcess enables creating a session for a given binary with artificial state. 9*a1e26a70SApple OSS DistributionsFor LLDB macros testing, this allows verifying assumptions about structs. 10*a1e26a70SApple OSS DistributionsFrom the binary, LLDB knows about the fields of a struct, and test attempting to access them will fail if they've been 11*a1e26a70SApple OSS Distributionsrenamed or removed. 12*a1e26a70SApple OSS DistributionsTheoretically a ScriptedProcess could be used to validate macros, but getting valid XNU state is an issue. 13*a1e26a70SApple OSS Distributions 14*a1e26a70SApple OSS DistributionsRun with e.g. 15*a1e26a70SApple OSS Distributions`PYTHONPATH=tools/lldbmacros xcrun --toolchain macos python3 tools/lldbmacros/tests/runtests.py BUILD/obj/DEVELOPMENT_ARM64_T6031/kernel.development.t6031` 16*a1e26a70SApple OSS Distributions 17*a1e26a70SApple OSS Distributions## *Any* LLDB session smoke tests 18*a1e26a70SApple OSS Distributions 19*a1e26a70SApple OSS DistributionsTo run the smoke LLDB tests within a LLDB session anywhere - either at-desk VM (quickest), at-desk machine or a coredump 20*a1e26a70SApple OSS Distributions(takes much more time). 21*a1e26a70SApple OSS Distributions 22*a1e26a70SApple OSS Distributions### Disclaimers 23*a1e26a70SApple OSS Distributions1. There are some macros that are ignored, see `IGNORES` variable (xno/tools/lldbmacros/tests/integration_smoke/test_lldb_macros.py) for more information. 24*a1e26a70SApple OSS Distributions2. There are some macros that are skipped for now - we will add at a later time. 25*a1e26a70SApple OSS Distributions3. Validation occurs only for the exit code of the macro run, not for the output. 26*a1e26a70SApple OSS Distributions 27*a1e26a70SApple OSS Distributions### Triggering the tests within a LLDB session (Live VM / Tethered device / Coredump) 28*a1e26a70SApple OSS Distributions1. `xcrun --sdk macosx.internal lldb [-c coredump file]` 29*a1e26a70SApple OSS Distributions2. `command script import <xnu_root>/tools/lldbmacros/tests/integration_smoke/test_lldb_macros.py` 30*a1e26a70SApple OSS Distributions----- 31*a1e26a70SApple OSS DistributionsNotice! if you need a gdb-remote session, you will have to enter it manually before running the macros. 32*a1e26a70SApple OSS Distributions* `gdb <[host=127.0.0.1:]port>` (e.g. 8000 or 1.3.3.7:8000). 33*a1e26a70SApple OSS Distributions----- 34*a1e26a70SApple OSS Distributions3. `macro_exec [macro_1] [macro_2] [...]` 35*a1e26a70SApple OSS Distributions4. `macro_coverage` 36*a1e26a70SApple OSS Distributions 37*a1e26a70SApple OSS Distributions### Triggering the tests from your local machine (at-desk) Live VM / Tethered Device 38*a1e26a70SApple OSS Distributions1. `xcrun --sdk macosx.internal python3 <xnu_root>/tools/lldbmacros/tests/integration_smoke/test_lldb_macros.py [[host=127.0.0.1:]<port>]` 39*a1e26a70SApple OSS Distributions 40*a1e26a70SApple OSS Distributions### Triggering the tests with customizations (pytest) - Live VM / Tethered Device 41*a1e26a70SApple OSS Distributions1. `xcrun --sdk macosx.internal python3 -m pytest <pytest_options> [--gdb-remote [host=127.0.0.1:]<port>] <xnu_root>/tools/lldbmacros/tests/integration_smoke/test_lldb_macros.py <pytest_arguments>` 42