Merge pull request #25 from delphix/master

Merge branch 'master' into '6.0/stage'

Author: Prakash Surya

.github/workflows/ci.yml

@@ -22,14 +22,14 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install busybox-static libelf-dev libdw-dev qemu-kvm zstd ${{ matrix.cc == 'clang' && 'libomp-dev' || '' }}
+          sudo apt-get install busybox-static libelf-dev libdw-dev qemu-kvm zstd ${{ matrix.cc == 'clang' && 'libomp-$(clang --version | sed -rn "s/.*clang version ([0-9]+).*/\\1/p")-dev' || '' }}
           pip install mypy
       - name: Generate version.py
         run: python setup.py --version
       - name: Check with mypy
         run: mypy --strict --no-warn-return-any drgn _drgn.pyi
       - name: Build and test with ${{ matrix.cc }}
-        run: python setup.py test
+        run: python setup.py test -K
 
   lint:
     runs-on: ubuntu-latest

.github/workflows/vmtest-build.yml

@@ -0,0 +1,28 @@
+name: vmtest Build
+
+on:
+  schedule:
+    - cron: '16 6 * * MON'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install libelf-dev
+          pip install aiohttp uritemplate
+      - name: Build and upload assets
+        run: python3 -m vmtest.manage --kernel-directory build/vmtest/linux.git --build-directory build/vmtest/kbuild -K
+      - name: Upload kernel build logs
+        if: always()
+        uses: actions/upload-artifact@v2
+        with:
+          name: kernel-build-logs
+          path: build/vmtest/kbuild/*.log
+          if-no-files-found: ignore

MANIFEST.in

@@ -3,4 +3,4 @@ recursive-include examples *.py
 recursive-include tests *.py
 recursive-include tools *.py
 recursive-include vmtest *.c *.py *.rst
-include util.py vmtest/config
+include COPYING util.py vmtest/config

README.rst

@@ -40,7 +40,7 @@ scripting support, drgn aims to make scripting as natural as possible so that
 debugging feels like coding. This makes it well-suited for introspecting the
 complex, inter-connected state in large programs. It is also designed as a
 library that can be used to build debugging and introspection tools; see the
-official `tools <https://github.com/osandov/drgn/tree/master/tools>`_.
+official `tools <https://github.com/osandov/drgn/tree/main/tools>`_.
 
 drgn was developed for debugging the Linux kernel (as an alternative to the
 `crash <http://people.redhat.com/anderson/>`_ utility), but it can also debug

_drgn.pyi

@@ -19,6 +19,7 @@ from typing import (
     Mapping,
     Optional,
     Sequence,
+    Tuple,
     Union,
     overload,
 )
@@ -105,7 +106,15 @@ class Program:
         >>> prog['jiffies']
         Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)
 
-        :param name: The object name.
+        :param name: Object name.
+        """
+        ...
+    def __contains__(self, name: str) -> bool:
+        """
+        Implement ``name in self``. Return whether an object (variable,
+        constant, or function) with the given name exists in the program.
+
+        :param name: Object name.
         """
         ...
     def variable(self, name: str, filename: Optional[str] = None) -> Object:
@@ -258,16 +267,16 @@ class Program:
         """
         ...
     def read_u8(self, address: IntegerLike, physical: bool = False) -> int:
-        ""
+        """ """
         ...
     def read_u16(self, address: IntegerLike, physical: bool = False) -> int:
-        ""
+        """ """
         ...
     def read_u32(self, address: IntegerLike, physical: bool = False) -> int:
-        ""
+        """ """
         ...
     def read_u64(self, address: IntegerLike, physical: bool = False) -> int:
-        ""
+        """ """
         ...
     def read_word(self, address: IntegerLike, physical: bool = False) -> int:
         """
@@ -1374,30 +1383,63 @@ class StackTrace:
     .. code-block:: python3
 
         for frame in trace:
-            if frame.symbol().name == 'io_schedule':
+            if frame.name == 'io_schedule':
                 print('Thread is doing I/O')
 
     :class:`str() <str>` returns a pretty-printed stack trace:
 
-    >>> print(prog.stack_trace(1))
-    #0  __schedule+0x25c/0x8ba
-    #1  schedule+0x3c/0x7e
-    #2  schedule_hrtimeout_range_clock+0x10c/0x118
-    #3  ep_poll+0x3ca/0x40a
-    #4  do_epoll_wait+0xb0/0xc6
-    #5  __x64_sys_epoll_wait+0x1a/0x1d
-    #6  do_syscall_64+0x55/0x17c
-    #7  entry_SYSCALL_64+0x7c/0x156
+    >>> prog.stack_trace(1)
+    #0  context_switch (kernel/sched/core.c:4339:2)
+    #1  __schedule (kernel/sched/core.c:5147:8)
+    #2  schedule (kernel/sched/core.c:5226:3)
+    #3  do_wait (kernel/exit.c:1534:4)
+    #4  kernel_wait4 (kernel/exit.c:1678:8)
+    #5  __do_sys_wait4 (kernel/exit.c:1706:13)
+    #6  do_syscall_64 (arch/x86/entry/common.c:47:14)
+    #7  entry_SYSCALL_64+0x7c/0x15b (arch/x86/entry/entry_64.S:112)
+    #8  0x4d49dd
 
-    The drgn CLI is set up so that stack traces are displayed with ``str()`` by
-    default.
+    The format is subject to change. The drgn CLI is set up so that stack
+    traces are displayed with ``str()`` by default.
     """
 
     def __getitem__(self, idx: IntegerLike) -> StackFrame: ...
 
 class StackFrame:
     """
     A ``StackFrame`` represents a single *frame* in a thread's call stack.
+
+    :class:`str() <str>` returns a pretty-printed stack frame:
+
+    >>> prog.stack_trace(1)[0]
+    #0 at 0xffffffffb64ac287 (__schedule+0x227/0x606) in context_switch at kernel/sched/core.c:4339:2 (inlined)
+
+    This includes more information than when printing the full stack trace. The
+    format is subject to change. The drgn CLI is set up so that stack frames
+    are displayed with ``str()`` by default.
+
+    The :meth:`[] <.__getitem__>` operator can look up function parameters,
+    local variables, and global variables in the scope of the stack frame:
+
+    >>> prog.stack_trace(1)[0]['prev'].pid
+    (pid_t)1
+    >>> prog.stack_trace(1)[0]['scheduler_running']
+    (int)1
+    """
+
+    name: Optional[str]
+    """
+    Name of the function at this frame, or ``None`` if it could not be
+    determined.
+    """
+
+    is_inline: bool
+    """
+    Whether this frame is for an inlined call.
+
+    An inline frame shares the same stack frame in memory as its caller.
+    Therefore, it has the same registers (including program counter and thus
+    symbol).
     """
 
     interrupted: bool
@@ -1413,8 +1455,36 @@ class StackFrame:
     particular, the program counter is the return address, which is typically
     the instruction after the call instruction.
     """
+
     pc: int
     """Program counter at this stack frame."""
+    def __getitem__(self, name: str) -> Object:
+        """
+        Implement ``self[name]``. Get the object (variable, function parameter,
+        constant, or function) with the given name in the scope of this frame.
+
+        If the object exists but has been optimized out, this returns an
+        :ref:`absent object <absent-objects>`.
+
+        :param name: Object name.
+        """
+        ...
+    def __contains__(self, name: str) -> bool:
+        """
+        Implement ``name in self``. Return whether an object with the given
+        name exists in the scope of this frame.
+
+        :param name: Object name.
+        """
+        ...
+    def source(self) -> Tuple[str, int, int]:
+        """
+        Get the source code location of this frame.
+
+        :return: Location as a ``(filename, line, column)`` triple.
+        :raises LookupError: if the source code location is not available
+        """
+        ...
     def symbol(self) -> Symbol:
         """
         Get the function symbol at this stack frame.
@@ -1952,11 +2022,14 @@ class FaultError(Exception):
     accessing a memory address which is not valid in a program).
     """
 
-    def __init__(self, address: int) -> None:
+    def __init__(self, message: str, address: int) -> None:
         """
+        :param message: :attr:`FaultError.message`
         :param address: :attr:`FaultError.address`
         """
         ...
+    message: str
+    """Error message."""
     address: int
     """Address that couldn't be accessed."""
 
@@ -1981,6 +2054,7 @@ class OutOfBoundsError(Exception):
 
     ...
 
+_elfutils_version: str
 _with_libkdumpfile: bool
 
 def _linux_helper_read_vm(

docs/advanced_usage.rst

@@ -35,7 +35,7 @@ The core functionality of drgn is implemented in C and is available as a C
 library, ``libdrgn``. See |drgn.h|_.
 
 .. |drgn.h| replace:: ``drgn.h``
-.. _drgn.h: https://github.com/osandov/drgn/blob/master/libdrgn/drgn.h.in
+.. _drgn.h: https://github.com/osandov/drgn/blob/main/libdrgn/drgn.h.in
 
 Full documentation can be generated by running ``doxygen`` in the ``libdrgn``
 directory of the source code. Note that the API and ABI are not yet stable.

docs/user_guide.rst

@@ -139,6 +139,8 @@ address it points to)::
     >>> print(hex(jiffiesp.value_()))
     0xffffffffbe405000
 
+.. _absent-objects:
+
 Absent Objects
 """"""""""""""
 
@@ -317,5 +319,5 @@ Next Steps
 
 Refer to the :doc:`api_reference`. Look through the :doc:`helpers`. Browse
 through the official `examples
-<https://github.com/osandov/drgn/tree/master/examples>`_ and `tools
-<https://github.com/osandov/drgn/tree/master/tools>`_.
+<https://github.com/osandov/drgn/tree/main/examples>`_ and `tools
+<https://github.com/osandov/drgn/tree/main/tools>`_.

drgn/__init__.py

@@ -73,6 +73,7 @@
     TypeMember,
     TypeParameter,
     TypeTemplateParameter,
+    _elfutils_version as _elfutils_version,
     _with_libkdumpfile as _with_libkdumpfile,
     cast,
     container_of,
@@ -195,7 +196,7 @@ def task_exe_path(task):
     :param args: Zero or more additional arguments to pass to the script. This
         is a :ref:`variable argument list <python:tut-arbitraryargs>`.
     """
-    # This is based on runpy.run_code, which we can't use because we want to
+    # This is based on runpy.run_path(), which we can't use because we want to
     # update globals even if the script throws an exception.
     saved_module = []
     try:

drgn/internal/cli.py

@@ -23,7 +23,7 @@ def displayhook(value: Any) -> None:
     setattr(builtins, "_", None)
     if isinstance(value, drgn.Object):
         text = value.format_(columns=shutil.get_terminal_size((0, 0)).columns)
-    elif isinstance(value, (drgn.StackTrace, drgn.Type)):
+    elif isinstance(value, (drgn.StackFrame, drgn.StackTrace, drgn.Type)):
         text = str(value)
     else:
         text = repr(value)
@@ -43,7 +43,7 @@ def displayhook(value: Any) -> None:
 def main() -> None:
     python_version = ".".join(str(v) for v in sys.version_info[:3])
     libkdumpfile = f'with{"" if drgn._with_libkdumpfile else "out"} libkdumpfile'
-    version = f"drgn {drgn.__version__} (using Python {python_version}, {libkdumpfile})"
+    version = f"drgn {drgn.__version__} (using Python {python_version}, elfutils {drgn._elfutils_version}, {libkdumpfile})"
     parser = argparse.ArgumentParser(prog="drgn", description="Scriptable debugger")
 
     program_group = parser.add_argument_group(

examples/linux/cgroup.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env drgn
 # Copyright (c) Facebook, Inc. and its affiliates.
 # SPDX-License-Identifier: GPL-3.0-or-later
 

examples/linux/fs_inodes.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env drgn
 # Copyright (c) Facebook, Inc. and its affiliates.
 # SPDX-License-Identifier: GPL-3.0-or-later
 

examples/linux/lsmod.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env drgn
 # Copyright (c) Facebook, Inc. and its affiliates.
 # SPDX-License-Identifier: GPL-3.0-or-later
 

examples/linux/ps.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env drgn
 # Copyright (c) Facebook, Inc. and its affiliates.
 # SPDX-License-Identifier: GPL-3.0-or-later
 

examples/linux/tcp_sock.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env drgn
 # Copyright (c) Facebook, Inc. and its affiliates.
 # SPDX-License-Identifier: GPL-3.0-or-later
 

libdrgn/.gitignore

@@ -11,6 +11,7 @@
 /config.log
 /config.status
 /configure
+/configure~
 /html
 /libtool
 /python/constants.c

libdrgn/configure.ac

@@ -1,7 +1,7 @@
 dnl Copyright (c) Facebook, Inc. and its affiliates.
 dnl SPDX-License-Identifier: GPL-3.0-or-later
 
-AC_INIT([libdrgn], [0.0.11],
+AC_INIT([libdrgn], [0.0.13],
 	[https://github.com/osandov/drgn/issues],,
 	[https://github.com/osandov/drgn])
 
@@ -15,6 +15,8 @@ AM_PROG_AR
 
 LT_INIT
 
+AC_SYS_LARGEFILE
+
 AC_ARG_ENABLE([openmp],
 	      [AS_HELP_STRING([--enable-openmp@<:@=ARG@:>@],
 			      [use OpenMP. ARG may be yes, no, or the name of