mirror of
https://github.com/JakeHillion/drgn.git
synced 2024-12-24 18:03:07 +00:00
a97f6c4fa2
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>
127 lines
2.6 KiB
ReStructuredText
127 lines
2.6 KiB
ReStructuredText
API Reference
|
|
=============
|
|
|
|
.. module:: drgn
|
|
|
|
Programs
|
|
--------
|
|
|
|
.. drgndoc:: Program
|
|
:exclude: (void|int|bool|float|complex|struct|union|class|enum|typedef|pointer|array|function)_type
|
|
.. drgndoc:: ProgramFlags
|
|
.. drgndoc:: FindObjectFlags
|
|
|
|
.. _api-filenames:
|
|
|
|
Filenames
|
|
^^^^^^^^^
|
|
|
|
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
|
|
refers to the source code file that contains the definition. It is matched with
|
|
:func:`filename_matches()`. If multiple definitions match, one is returned
|
|
arbitrarily.
|
|
|
|
.. drgndoc:: filename_matches
|
|
|
|
.. _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.
|
|
|
|
.. drgndoc:: program_from_core_dump
|
|
.. drgndoc:: program_from_kernel
|
|
.. drgndoc:: program_from_pid
|
|
|
|
Platforms
|
|
^^^^^^^^^
|
|
|
|
.. drgndoc:: Platform
|
|
.. drgndoc:: Architecture
|
|
.. drgndoc:: PlatformFlags
|
|
.. drgndoc:: Register
|
|
.. drgndoc:: host_platform
|
|
|
|
Languages
|
|
^^^^^^^^^
|
|
|
|
.. drgndoc:: Language
|
|
|
|
Objects
|
|
-------
|
|
|
|
.. drgndoc:: Object
|
|
.. drgndoc:: NULL
|
|
.. drgndoc:: cast
|
|
.. drgndoc:: reinterpret
|
|
.. drgndoc:: container_of
|
|
|
|
Symbols
|
|
-------
|
|
|
|
.. drgndoc:: Symbol
|
|
|
|
Stack Traces
|
|
------------
|
|
|
|
Stack traces are retrieved with :meth:`Program.stack_trace()`.
|
|
|
|
.. drgndoc:: StackTrace
|
|
.. drgndoc:: StackFrame
|
|
|
|
.. _api-reference-types:
|
|
|
|
Types
|
|
-----
|
|
|
|
.. drgndoc:: Type
|
|
.. drgndoc:: TypeMember
|
|
.. drgndoc:: TypeEnumerator
|
|
.. drgndoc:: TypeParameter
|
|
.. drgndoc:: TypeKind
|
|
.. drgndoc:: PrimitiveType
|
|
.. drgndoc:: Qualifiers
|
|
|
|
.. _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()`.
|
|
|
|
.. 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
|
|
|
|
Miscellaneous
|
|
-------------
|
|
|
|
.. drgndoc:: sizeof
|
|
.. drgndoc:: execscript
|
|
.. drgndoc:: IntegerLike
|
|
.. drgndoc:: Path
|
|
|
|
Exceptions
|
|
----------
|
|
|
|
.. drgndoc:: FaultError
|
|
.. drgndoc:: MissingDebugInfoError
|
|
.. drgndoc:: OutOfBoundsError
|