Merge branch 'master' into '6.0/stage'

.github/workflows/sync-with-master.yml

@@ -0,0 +1,21 @@
+on:
+  push:
+    branches:
+      - master
+  schedule:
+    - cron:  '0 0 * * *'
+
+jobs:
+  sync:
+    strategy:
+      matrix:
+        branch:
+          - 6.0/stage
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v2
+      - uses: delphix/actions/sync-with-master@master
+        with:
+          branch-to-sync: ${{ matrix.branch }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -4,6 +4,7 @@
 /.mypy_cache
 /build
 /coverage.info
+/cscope.*
 /dist
 /docs/_build
 /drgn.egg-info

.travis.yml

@@ -1,169 +1,27 @@
-# Generated by scripts/generate_travis_yml.py
-
 dist: bionic
 
-jobs:
-  include:
-    - language: python
-      python: 3.8
-      addons:
-        apt:
-          packages:
-            - libbz2-dev
-            - liblzma-dev
-            - zlib1g-dev
-      install:
-      script: python setup.py build -j "$(nproc)" test
-    - language: python
-      python: 3.7
-      addons:
-        apt:
-          packages:
-            - libbz2-dev
-            - liblzma-dev
-            - zlib1g-dev
-      install:
-      script: python setup.py build -j "$(nproc)" test
-    - language: python
-      python: 3.6
-      addons:
-        apt:
-          packages:
-            - libbz2-dev
-            - liblzma-dev
-            - zlib1g-dev
-      install:
-      script: python setup.py build -j "$(nproc)" test
-    - name: "vmtest Linux 5.6"
-      language: minimal
-      env: KERNEL=5.6
-      addons:
-        apt:
-          packages:
-            - python3
-            - python3-setuptools
-            - qemu-kvm
-            - rsync
-            - zstd
-      install: sudo adduser "$USER" kvm
-      before_script:
-        # The double sudo is necessary to pick up the new group membership.
-        - sudo -E sudo -E -u "$USER" scripts/vmtest/run.sh -k "$KERNEL"'.*' -o -d ~ ~/root.img; exitstatus=$?
-        # Exit status 0 is success, 1 is test failure (should fail in the script
-        # step), anything else is an error (should fail here).
-        - test $exitstatus -le 1
-      script: test $exitstatus -eq 0
-    - name: "vmtest Linux 5.5"
-      language: minimal
-      env: KERNEL=5.5
-      addons:
-        apt:
-          packages:
-            - python3
-            - python3-setuptools
-            - qemu-kvm
-            - rsync
-            - zstd
-      install: sudo adduser "$USER" kvm
-      before_script:
-        # The double sudo is necessary to pick up the new group membership.
-        - sudo -E sudo -E -u "$USER" scripts/vmtest/run.sh -k "$KERNEL"'.*' -o -d ~ ~/root.img; exitstatus=$?
-        # Exit status 0 is success, 1 is test failure (should fail in the script
-        # step), anything else is an error (should fail here).
-        - test $exitstatus -le 1
-      script: test $exitstatus -eq 0
-    - name: "vmtest Linux 5.4"
-      language: minimal
-      env: KERNEL=5.4
-      addons:
-        apt:
-          packages:
-            - python3
-            - python3-setuptools
-            - qemu-kvm
-            - rsync
-            - zstd
-      install: sudo adduser "$USER" kvm
-      before_script:
-        # The double sudo is necessary to pick up the new group membership.
-        - sudo -E sudo -E -u "$USER" scripts/vmtest/run.sh -k "$KERNEL"'.*' -o -d ~ ~/root.img; exitstatus=$?
-        # Exit status 0 is success, 1 is test failure (should fail in the script
-        # step), anything else is an error (should fail here).
-        - test $exitstatus -le 1
-      script: test $exitstatus -eq 0
-    - name: "vmtest Linux 4.19"
-      language: minimal
-      env: KERNEL=4.19
-      addons:
-        apt:
-          packages:
-            - python3
-            - python3-setuptools
-            - qemu-kvm
-            - rsync
-            - zstd
-      install: sudo adduser "$USER" kvm
-      before_script:
-        # The double sudo is necessary to pick up the new group membership.
-        - sudo -E sudo -E -u "$USER" scripts/vmtest/run.sh -k "$KERNEL"'.*' -o -d ~ ~/root.img; exitstatus=$?
-        # Exit status 0 is success, 1 is test failure (should fail in the script
-        # step), anything else is an error (should fail here).
-        - test $exitstatus -le 1
-      script: test $exitstatus -eq 0
-    - name: "vmtest Linux 4.14"
-      language: minimal
-      env: KERNEL=4.14
-      addons:
-        apt:
-          packages:
-            - python3
-            - python3-setuptools
-            - qemu-kvm
-            - rsync
-            - zstd
-      install: sudo adduser "$USER" kvm
-      before_script:
-        # The double sudo is necessary to pick up the new group membership.
-        - sudo -E sudo -E -u "$USER" scripts/vmtest/run.sh -k "$KERNEL"'.*' -o -d ~ ~/root.img; exitstatus=$?
-        # Exit status 0 is success, 1 is test failure (should fail in the script
-        # step), anything else is an error (should fail here).
-        - test $exitstatus -le 1
-      script: test $exitstatus -eq 0
-    - name: "vmtest Linux 4.9"
-      language: minimal
-      env: KERNEL=4.9
-      addons:
-        apt:
-          packages:
-            - python3
-            - python3-setuptools
-            - qemu-kvm
-            - rsync
-            - zstd
-      install: sudo adduser "$USER" kvm
-      before_script:
-        # The double sudo is necessary to pick up the new group membership.
-        - sudo -E sudo -E -u "$USER" scripts/vmtest/run.sh -k "$KERNEL"'.*' -o -d ~ ~/root.img; exitstatus=$?
-        # Exit status 0 is success, 1 is test failure (should fail in the script
-        # step), anything else is an error (should fail here).
-        - test $exitstatus -le 1
-      script: test $exitstatus -eq 0
-    - name: "vmtest Linux 4.4"
-      language: minimal
-      env: KERNEL=4.4
-      addons:
-        apt:
-          packages:
-            - python3
-            - python3-setuptools
-            - qemu-kvm
-            - rsync
-            - zstd
-      install: sudo adduser "$USER" kvm
-      before_script:
-        # The double sudo is necessary to pick up the new group membership.
-        - sudo -E sudo -E -u "$USER" scripts/vmtest/run.sh -k "$KERNEL"'.*' -o -d ~ ~/root.img; exitstatus=$?
-        # Exit status 0 is success, 1 is test failure (should fail in the script
-        # step), anything else is an error (should fail here).
-        - test $exitstatus -le 1
-      script: test $exitstatus -eq 0
+language: python
+python:
+  - '3.8'
+  - '3.7'
+  - '3.6'
+install:
+  # Upstream defaults to world-read-writeable /dev/kvm. Debian/Ubuntu override
+  # this; see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=892945. We want
+  # the upstream default.
+  - sudo echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /lib/udev/rules.d/99-fix-kvm.rules > /dev/null
+  - sudo udevadm control --reload-rules
+  # On systemd >= 238 we can use udevadm trigger -w and remove udevadm settle.
+  - sudo udevadm trigger /dev/kvm
+  - sudo udevadm settle
+script: python setup.py test -K
+
+addons:
+  apt:
+    packages:
+      - busybox-static
+      - libbz2-dev
+      - liblzma-dev
+      - qemu-kvm
+      - zlib1g-dev
+      - zstd

MANIFEST.in

@@ -1,3 +1,6 @@
 recursive-include docs *.py *.rst
+recursive-include examples *.py
 recursive-include tests *.py
-recursive-include scripts/vmtest *.py *.rst *.sh
+recursive-include tools *.py
+recursive-include vmtest *.c *.py *.rst
+include util.py vmtest/config

README.rst

@@ -39,11 +39,12 @@ Although other debuggers like `GDB <https://www.gnu.org/software/gdb/>`_ have
 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 for more purpose-built tools.
+library that can be used to build debugging and introspection tools; see the
+official `tools <https://github.com/osandov/drgn/tree/master/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
-userspace programs written in C. C++ support is planned.
+userspace programs written in C. C++ support is in progress.
 
 .. end-introduction
 

_drgn.pyi

@@ -203,7 +203,7 @@ class Program:
         ...
     def pointer_type(
         self,
-        type: Type,
+        type: Union[str, Type],
         qualifiers: Optional[Qualifiers] = None,
         *,
         language: Optional[Language] = None,
@@ -236,6 +236,30 @@ class Program:
         :raises ValueError: if *size* is negative
         """
         ...
+    def read_u8(self, address: int, physical: bool = False) -> int: ...
+    def read_u16(self, address: int, physical: bool = False) -> int: ...
+    def read_u32(self, address: int, physical: bool = False) -> int: ...
+    def read_u64(self, address: int, physical: bool = False) -> int: ...
+    def read_word(self, address: int, physical: bool = False) -> int:
+        """
+        Read an unsigned integer from the program's memory in the program's
+        byte order.
+
+        :meth:`read_u8()`, :meth:`read_u16()`, :meth:`read_u32()`, and
+        :meth:`read_u64()` read an 8-, 16-, 32-, or 64-bit unsigned integer,
+        respectively. :meth:`read_word()` reads a program word-sized unsigned
+        integer.
+
+        For signed integers, alternate byte order, or other formats, you can
+        use :meth:`read()` and :meth:`int.from_bytes()` or the :mod:`struct`
+        module.
+
+        :param address: Address of the integer.
+        :param physical: Whether *address* is a physical memory address; see
+            :meth:`read()`.
+        :raises FaultError: if the address is invalid; see :meth:`read()`
+        """
+        ...
     def add_memory_segment(
         self,
         address: int,
@@ -665,7 +689,7 @@ class Object:
     """
     Size in bits of this object if it is a bit field, ``None`` if it is not.
     """
-    def __getattribute__(self, name: str) -> Any:
+    def __getattribute__(self, name: str) -> Object:
         """
         Implement ``self.name``.
 
@@ -679,7 +703,7 @@ class Object:
         :param name: Attribute name.
         """
         ...
-    def __getitem__(self, idx: int) -> Object:
+    def __getitem__(self, idx: Union[int, Object]) -> Object:
         """
         Implement ``self[idx]``. Get the array element at the given index.
 
@@ -961,7 +985,6 @@ def container_of(ptr: Object, type: Union[str, Type], member: str) -> Object:
 
     :param ptr: The pointer.
     :param type: The type of the containing object.
-    :type type: str or Type
     :param member: The name of the member in ``type``.
     :raises TypeError: if the object is not a pointer or the type is not a
         structure, union, or class type
@@ -1027,13 +1050,20 @@ class StackFrame:
 
     pc: int
     """
-    The return address at this stack frame, i.e., the value of the program
-    counter when control returns to this frame.
+    The program counter at this stack frame.
+
+    For the innermost frame, this is typically the instruction that was being
+    executed when the stack trace was captured. For function calls, this is
+    generally the return address, i.e., the value of the program counter when
+    control returns to this frame.
     """
     def symbol(self) -> Symbol:
         """
-        Get the function symbol at this stack frame. This is equivalent to
-        :meth:`prog.symbol(frame.pc) <Program.symbol>`.
+        Get the function symbol at this stack frame.
+
+        This may differ from :meth:`prog.symbol(frame.pc) <Program.symbol>`, as
+        for function calls, the program counter may be adjusted to the call
+        instruction instead of the return address.
         """
         ...
     def register(self, reg: Union[str, int, Register]) -> int:
@@ -1603,3 +1633,14 @@ class OutOfBoundsError(Exception):
     """
 
     ...
+
+_with_libkdumpfile: bool
+
+def _linux_helper_read_vm(prog, pgtable, address, size): ...
+def _linux_helper_radix_tree_lookup(root, index): ...
+def _linux_helper_idr_find(idr, id): ...
+def _linux_helper_find_pid(ns, pid): ...
+def _linux_helper_pid_task(pid, pid_type): ...
+def _linux_helper_find_task(ns, pid): ...
+def _linux_helper_task_state_to_char(task): ...
+def _linux_helper_pgtable_l5_enabled(prog): ...

debian/rules

@@ -2,3 +2,17 @@
 
 %:
 	dh $@ --with python3 --buildsystem=pybuild
+
+override_dh_auto_test:
+	#
+	# Don't run drgn's tests during the build step; The repo comes
+	# with its own testing that takes place elsewhere ->
+	# https://travis-ci.org/github/delphix/drgn/branches
+	#
+	# Ideally it wouldn't hurt having them run here too but due to
+	# drgn's testing setup, we'd have to override pybuild's default
+	# behavior. Since drgn is not a project that is owned by us,
+	# disabling tests here makes even more sense as we won't have
+	# to adjust the setup here every time a change in the test
+	# framework of drgn is applied upstream.
+	#

docs/advanced_usage.rst

@@ -94,4 +94,4 @@ Some of drgn's behavior can be modified through environment variables:
 
 ``DRGN_USE_LIBKDUMPFILE_FOR_ELF``
     Whether drgn should use libkdumpfile for ELF vmcores (0 or 1). The default
-    is 1 if drgn was built with libkdumpfile support.
+    is 0. This functionality will be removed in the future.

docs/exts/drgndoc/format.py

@@ -266,6 +266,9 @@ def _add_function_info(
         node = resolved.node
 
         if rst:
+            if node.docstring is None:
+                want_rtype = False
+
             params_need_type = set()
             params_have_type = set()
             for line in lines: