JakeHillion/drgn
1
0
Fork 0
mirror of https://github.com/JakeHillion/drgn.git synced 2024-12-25 02:13:06 +00:00
Code Issues Packages Projects Releases Wiki Activity
2252bef1a7
drgn/docs/api_reference.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

127 lines
2.6 KiB
ReStructuredText
Raw Normal View History

Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
API Reference
=============
.. module:: drgn
Programs
--------
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: Program
Associate types with program I originally envisioned types as dumb descriptors. This mostly works for C because in C, types are fairly simple. However, even then the drgn_program_member_info() API is awkward. You should be able to look up a member directly from a type, but we need the program for caching purposes. This has also held me back from adding offsetof() or has_member() APIs. Things get even messier with C++. C++ template parameters can be objects (e.g., template <int N>). Such parameters would best be represented by a drgn object, which we need a drgn program for. Static members are a similar case. So, let's reimagine types as being owned by a program. This has a few parts: 1. In libdrgn, simple types are now created by factory functions, drgn_foo_type_create(). 2. To handle their variable length fields, compound types, enum types, and function types are constructed with a "builder" API. 3. Simple types are deduplicated. 4. The Python type factory functions are replaced by methods of the Program class. 5. While we're changing the API, the parameters to pointer_type() and array_type() are reordered to be more logical (and to allow pointer_type() to take a default size of None for the program's default pointer size). 6. Likewise, the type factory methods take qualifiers as a keyword argument only. A big part of this change is updating the tests and splitting up large test cases into smaller ones in a few places. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-07-16 00:34:56 +01:00
:exclude: (void|int|bool|float|complex|struct|union|class|enum|typedef|pointer|array|function)_type
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: ProgramFlags
.. drgndoc:: FindObjectFlags
libdrgn/python: add Program.object()
2019-04-29 02:07:21 +01:00
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
.. _api-filenames:
Filenames
^^^^^^^^^
libdrgn/python: add Program.object()
2019-04-29 02:07:21 +01:00
The :meth:`Program.type()`, :meth:`Program.object()`,
:meth:`Program.variable()`, :meth:`Program.constant()`, and
:meth:`Program.function()` methods all take a *filename* parameter to
distinguish between multiple definitions with the same name. The filename
libdrgn: make program components pluggable Currently, programs can be created for three main use-cases: core dumps, the running kernel, and a running process. However, internally, the program memory, types, and symbols are pluggable. Expose that as a callback API, which makes it possible to use drgn in much more creative ways.
2019-05-10 07:53:16 +01:00
refers to the source code file that contains the definition. It is matched with
:func:`filename_matches()`. If multiple definitions match, one is returned
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
arbitrarily.
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: filename_matches
libdrgn: make program components pluggable Currently, programs can be created for three main use-cases: core dumps, the running kernel, and a running process. However, internally, the program memory, types, and symbols are pluggable. Expose that as a callback API, which makes it possible to use drgn in much more creative ways.
2019-05-10 07:53:16 +01:00
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
.. _api-program-constructors:
Program Constructors
^^^^^^^^^^^^^^^^^^^^
The drgn command line interface automatically creates a :class:`Program` named
``prog``. However, drgn may also be used as a library without the CLI, in which
case a ``Program`` must be created manually.
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: program_from_core_dump
.. drgndoc:: program_from_kernel
.. drgndoc:: program_from_pid
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
libdrgn: generalize architecture to platform For stack trace support, we'll need to have some architecture-specific functionality. drgn's current notion of an architecture doesn't actually include the instruction set architecture. This change expands it to a "platform", which includes the ISA as well as the existing flags.
2019-07-29 08:57:28 +01:00
Platforms
^^^^^^^^^
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: Platform
.. drgndoc:: Architecture
.. drgndoc:: PlatformFlags
.. drgndoc:: Register
.. drgndoc:: host_platform
libdrgn: generalize architecture to platform For stack trace support, we'll need to have some architecture-specific functionality. drgn's current notion of an architecture doesn't actually include the instruction set architecture. This change expands it to a "platform", which includes the ISA as well as the existing flags.
2019-07-29 08:57:28 +01:00
libdrgn/python: add Language to Python bindings
2020-02-21 23:08:37 +00:00
Languages
^^^^^^^^^
.. drgndoc:: Language
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
Objects
-------
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: Object
.. drgndoc:: NULL
.. drgndoc:: cast
.. drgndoc:: reinterpret
.. drgndoc:: container_of
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
libdrgn: add symbol table interface Now that we're not overloading the name "symbol", we can define struct drgn_symbol as a symbol table entry. For now, this is very minimal: it's just a name, address, and size. We can then add a way to find the symbol for a given address, drgn_program_find_symbol(). For now, this is only supported through the actual ELF symbol tables. However, in the future, we can probably support adding "symbol finders".
2019-07-25 08:47:13 +01:00
Symbols
-------
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: Symbol
libdrgn: add symbol table interface Now that we're not overloading the name "symbol", we can define struct drgn_symbol as a symbol table entry. For now, this is very minimal: it's just a name, address, and size. We can then add a way to find the symbol for a given address, drgn_program_find_symbol(). For now, this is only supported through the actual ELF symbol tables. However, in the future, we can probably support adding "symbol finders".
2019-07-25 08:47:13 +01:00
Add basic stack trace support For now, we only support stack traces for the Linux kernel (at least v4.9) on x86-64, and we only support getting the program counter and corresponding function symbol from each stack frame.
2019-07-29 22:41:33 +01:00
Stack Traces
------------
libdrgn: stack_trace: support unwinding stack from thread ID When debugging the Linux kernel, it's inconvenient to have to get the task_struct of a thread in order to get its stack trace. This adds support for looking it up solely by PID. In that case, we do the find_task() inside of libdrgn. This also gives us stack trace support for userspace core dumps almost for free since we already added support for NT_PRSTATUS.
2019-10-26 00:11:14 +01:00
Stack traces are retrieved with :meth:`Program.stack_trace()`.
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: StackTrace
.. drgndoc:: StackFrame
libdrgn: support getting register values from stack frames Currently, the only information available from a stack frame is the program counter. Eventually, we'd like to add support for getting arguments and local variables, but that will require more work. In the mean time, we can at least get the values of other registers. A determined user can read the assembly for the code they're debugging and derive the values of variables from the registers.
2019-10-18 10:42:51 +01:00
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
.. _api-reference-types:
Types
-----
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: Type
.. drgndoc:: TypeMember
.. drgndoc:: TypeEnumerator
.. drgndoc:: TypeParameter
.. drgndoc:: TypeKind
.. drgndoc:: PrimitiveType
.. drgndoc:: Qualifiers
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
.. _api-type-constructors:
Type Constructors
^^^^^^^^^^^^^^^^^
Custom drgn types can be created with the following factory functions. These
can be used just like types obtained from :meth:`Program.type()`.
Associate types with program I originally envisioned types as dumb descriptors. This mostly works for C because in C, types are fairly simple. However, even then the drgn_program_member_info() API is awkward. You should be able to look up a member directly from a type, but we need the program for caching purposes. This has also held me back from adding offsetof() or has_member() APIs. Things get even messier with C++. C++ template parameters can be objects (e.g., template <int N>). Such parameters would best be represented by a drgn object, which we need a drgn program for. Static members are a similar case. So, let's reimagine types as being owned by a program. This has a few parts: 1. In libdrgn, simple types are now created by factory functions, drgn_foo_type_create(). 2. To handle their variable length fields, compound types, enum types, and function types are constructed with a "builder" API. 3. Simple types are deduplicated. 4. The Python type factory functions are replaced by methods of the Program class. 5. While we're changing the API, the parameters to pointer_type() and array_type() are reordered to be more logical (and to allow pointer_type() to take a default size of None for the program's default pointer size). 6. Likewise, the type factory methods take qualifiers as a keyword argument only. A big part of this change is updating the tests and splitting up large test cases into smaller ones in a few places. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-07-16 00:34:56 +01:00
.. drgndoc:: Program.void_type
.. drgndoc:: Program.int_type
.. drgndoc:: Program.bool_type
.. drgndoc:: Program.float_type
.. drgndoc:: Program.complex_type
.. drgndoc:: Program.struct_type
.. drgndoc:: Program.union_type
.. drgndoc:: Program.class_type
.. drgndoc:: Program.enum_type
.. drgndoc:: Program.typedef_type
.. drgndoc:: Program.pointer_type
.. drgndoc:: Program.array_type
.. drgndoc:: Program.function_type
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
python: add execscript() On many occasions, I've wanted to build and iterate on a script while exploring in an interactive session. This has involved various workarounds, like copy-and-paste of the work-in-progress script into the REPL, using importlib.reload(), or adding code.interact() at the end of the script. These workflows aren't very convenient. Add execscript(), which runs a script as if it was run from the REPL, adding all defined functions and variables to the global scope so that iterating on the script further is easy.
2019-06-28 20:48:45 +01:00
Miscellaneous
-------------
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: sizeof
.. drgndoc:: execscript
Add IntegerLike type annotation Lots if interfaces in drgn transparently turn an integer Object into an int by using __index__(), so add an IntegerLike protocol for this and use it everywhere applicable. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-08-13 22:47:59 +01:00
.. drgndoc:: IntegerLike
Add Path type alias Rather than duplicating Union[str, bytes, os.PathLike] everywhere, add an alias. Also make it explicitly os.PathLike[str] or os.PathLike[bytes] to get rid of some mypy --strict errors. Signed-off-by: Omar Sandoval <osandov@osandov.com>
2020-08-13 23:27:20 +01:00
.. drgndoc:: Path
python: add execscript() On many occasions, I've wanted to build and iterate on a script while exploring in an interactive session. This has involved various workarounds, like copy-and-paste of the work-in-progress script into the REPL, using importlib.reload(), or adding code.interact() at the end of the script. These workflows aren't very convenient. Add execscript(), which runs a script as if it was run from the REPL, adding all defined functions and variables to the global scope so that iterating on the script further is easy.
2019-06-28 20:48:45 +01:00
Document with Sphinx drgn has pretty thorough in-program documentation, but it doesn't have a nice overview or introduction to the basic concepts. This commit adds that using Sphinx. In order to avoid documenting everything in two places, the libdrgn bindings have their docstrings generated from the API documentation. The alternative would be to use Sphinx's autodoc extension, but that's not as flexible and would also require building the extension to build the docs. The documentation for the helpers is generated using autodoc and a small custom extension.
2019-04-04 09:27:23 +01:00
Exceptions
----------
Add type hint stubs and generate documentation from them I've been wanting to add type hints for the _drgn C extension for awhile. The main blocker was that there is a large overlap between the documentation (in docs/api_reference.rst) and the stub file, and I really didn't want to duplicate the information. Therefore, it was a requirement that the the documentation could be generated from the stub file, or vice versa. Unfortunately, none of the existing tools that I could find supported this very well. So, I bit the bullet and wrote my own Sphinx extension that uses the stub file as the source of truth (and subsumes my old autopackage extension and gen_docstrings script). The stub file is probably incomplete/inaccurate in places, but this should be a good starting point to improve on. Closes #22.
2020-02-25 19:43:01 +00:00
.. drgndoc:: FaultError
.. drgndoc:: MissingDebugInfoError
.. drgndoc:: OutOfBoundsError
Reference in New Issue Copy Permalink