Debian Codegraph @

libdrgn/python/drgnpy.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // SPDX-License-Identifier: LGPL-2.1-or-later
3
4 #ifndef DRGNPY_H
5 #define DRGNPY_H
6
7 #define PY_SSIZE_T_CLEAN
8
9 // IWYU pragma: begin_exports
10 #include <Python.h>
11 #include "structmember.h"
12
13 #include "docstrings.h"
14 #include "../cleanup.h"
15 #include "../drgn_internal.h"
16 // IWYU pragma: end_exports
17
18 #include "../hash_table.h"
19 #include "../pp.h"
20 #include "../program.h"
21 #include "../symbol.h"
22 #include "../vector.h"
23
24 #if PY_VERSION_HEX < 0x030900a1
25 static inline PyObject *PyObject_CallNoArgs(PyObject *func)
26 {
27 return PyObject_CallFunctionObjArgs(func, NULL);
28 }
29 static inline PyObject *PyObject_CallOneArg(PyObject *callable, PyObject *arg)
30 {
31 return PyObject_CallFunctionObjArgs(callable, arg, NULL);
32 }
33 #endif
34
35 #if PY_VERSION_HEX < 0x030a00a3
36 static inline int PyModule_AddObjectRef(PyObject *mod, const char *name,
37 PyObject *value)
38 {
39 Py_XINCREF(value);
40 int ret = PyModule_AddObject(mod, name, value);
41 if (ret)
42 Py_XDECREF(value);
43 return ret;
44 }
45 #endif
46
47 #if PY_VERSION_HEX < 0x030d00a1
48 static inline int PyModule_Add(PyObject *mod, const char *name, PyObject *value)
49 {
50 int ret = PyModule_AddObject(mod, name, value);
51 if (ret)
52 Py_XDECREF(value);
53 return ret;
54 }
55
56 #define PyThreadState_GetUnchecked _PyThreadState_UncheckedGet
57 #endif
58
59 #if PY_VERSION_HEX < 0x030e00a5
60 #define Py_HashPointer _Py_HashPointer
61 #endif
62
63 #define DRGNPY_PUBLIC __attribute__((__visibility__("default")))
64
65 // Added in Python 3.14. We provide a fallback for older versions.
66 int PyLong_IsNegative(PyObject *obj);
67
68 #if PY_VERSION_HEX < 0x030e00a1
69 static inline PyObject *PyLong_FromInt64(int64_t value)
70 {
71 return PyLong_FromLongLong(value);
72 }
73 static inline PyObject *PyLong_FromUInt32(uint32_t value)
74 {
75 return PyLong_FromUnsignedLong(value);
76 }
77 static inline PyObject *PyLong_FromUInt64(uint64_t value)
78 {
79 return PyLong_FromUnsignedLongLong(value);
80 }
81
82 int PyLong_AsInt64(PyObject *obj, int64_t *value);
83 int PyLong_AsUInt32(PyObject *obj, uint32_t *value);
84 int PyLong_AsUInt64(PyObject *obj, uint64_t *value);
85 #endif
86
87 // These variants don't exist as of Python 3.14.
88 static inline PyObject *PyLong_FromUInt8(uint8_t value)
89 {
90 return PyLong_FromUnsignedLong(value);
91 }
92 static inline PyObject *PyLong_FromUInt16(uint16_t value)
93 {
94 return PyLong_FromUnsignedLong(value);
95 }
96 int PyLong_AsUInt16(PyObject *obj, uint16_t *value);
97
98 #define Py_RETURN_BOOL(cond) do { \
99 if (cond) \
100 Py_RETURN_TRUE; \
101 else \
102 Py_RETURN_FALSE; \
103 } while (0)
104
105 /**
106 * Return from a PyGetSetDef setter with an error if attempting to delete the
107 * attribute.
108 */
109 #define SETTER_NO_DELETE(name, value) do { \
110 if (!(value)) { \
111 PyErr_Format(PyExc_AttributeError, \
112 "can't delete '%s' attribute", (name)); \
113 return -1; \
114 } \
115 } while (0)
116
117 static inline void pydecrefp(void *p)
118 {
119 Py_XDECREF(*(PyObject **)p);
120 }
121
122 /** Scope guard that wraps PyGILState_Ensure() and PyGILState_Release(). */
123 #define PyGILState_guard() \
124 __attribute__((__cleanup__(PyGILState_Releasep), __unused__)) \
125 PyGILState_STATE PP_UNIQUE(gstate) = PyGILState_Ensure()
126 static inline void PyGILState_Releasep(PyGILState_STATE *gstatep)
127 {
128 PyGILState_Release(*gstatep);
129 }
130
131 /** Call @c Py_XDECREF() when the variable goes out of scope. */
132 #define _cleanup_pydecref_ _cleanup_(pydecrefp)
133
134 typedef struct {
135 PyObject_HEAD
136 struct drgn_object obj;
137 } DrgnObject;
138
139 typedef struct {
140 PyObject_HEAD
141 struct drgn_type *type;
142 enum drgn_qualifiers qualifiers;
143 /*
144 * Cache of attributes which were previously converted from a struct
145 * drgn_type member or used to create the type.
146 */
147 PyObject *attr_cache;
148 } DrgnType;
149
150 typedef struct {
151 PyObject_HEAD
152 struct drgn_symbol_index index;
153 } SymbolIndex;
154
155 typedef struct {
156 PyObject_HEAD
157 /*
158 * "Python-friendly" name used for the object, which may differ from the
159 * language name if the language name is not a valid identifier (e.g.,
160 * C++).
161 */
162 const char *attr_name;
163 const struct drgn_language *language;
164 } Language;
165
166 typedef struct {
167 PyObject_HEAD
168 struct drgn_memory_search_iterator *it;
169 } MemorySearchIterator;
170
171 typedef struct {
172 PyObject_HEAD
173 struct drgn_module *module;
174 } Module;
175
176 typedef struct {
177 PyObject_HEAD
178 struct drgn_module_iterator *it;
179 } ModuleIterator;
180
181 typedef struct {
182 PyObject_HEAD
183 struct drgn_module *module;
184 } ModuleSectionAddresses;
185
186 typedef struct {
187 PyObject_HEAD
188 struct drgn_module_section_address_iterator *it;
189 } ModuleSectionAddressesIterator;
190
191 typedef struct {
192 PyObject_HEAD
193 DrgnObject *obj;
194 uint64_t index, end;
195 int step;
196 } ObjectIterator;
197
198 typedef struct {
199 PyObject_HEAD
200 struct drgn_platform *platform;
201 } Platform;
202
203 DEFINE_HASH_SET_TYPE(pyobjectp_set, PyObject *);
204
205 typedef struct {
206 PyObject_HEAD
207 struct drgn_program prog;
208 PyObject *cache;
209 PyObject *config;
210 /*
211 * Set of objects that we need to hold a reference to during the
212 * lifetime of the Program.
213 */
214 struct pyobjectp_set objects;
215 } Program;
216
217 typedef struct {
218 PyObject_HEAD
219 struct drgn_debug_info_options *options;
220 // If this is a Program's default debug info options, the Program.
221 // Otherwise, NULL.
222 Program *prog;
223 } DebugInfoOptions;
224
225 typedef struct {
226 PyObject_HEAD
227 struct drgn_thread thread;
228 } Thread;
229
230 typedef struct {
231 PyObject_HEAD
232 Program *prog;
233 struct drgn_thread_iterator *iterator;
234 } ThreadIterator;
235
236 typedef struct {
237 PyObject_HEAD
238 const struct drgn_register *reg;
239 } Register;
240
241 typedef struct {
242 PyObject_HEAD
243 struct drgn_source_location_list *locs;
244 } SourceLocationList;
245
246 typedef struct {
247 PyObject_HEAD
248 struct drgn_stack_trace *trace;
249 } StackTrace;
250
251 typedef struct {
252 PyObject_HEAD
253 StackTrace *trace;
254 size_t i;
255 } StackFrame;
256
257 typedef struct {
258 PyObject_HEAD
259 PyObject *name_obj; /* object owning the reference to the symbol name */
260 struct drgn_symbol *sym;
261 } Symbol;
262
263 typedef struct {
264 PyObject_HEAD
265 PyObject *name;
266 PyObject *value;
267 } TypeEnumerator;
268
269 typedef struct {
270 PyObject_HEAD
271 PyObject *obj;
272 /*
273 * If DRGNPY_LAZY_OBJECT_EVALUATED, obj is the evaluated Object.
274 * If DRGNPY_LAZY_OBJECT_CALLABLE, obj is a Python callable that should
275 * return the Object.
276 * Otherwise, this must be evaluated and wrapped, and obj is a reference
277 * required to keep this alive.
278 */
279 union drgn_lazy_object *lazy_obj;
280 } LazyObject;
281
282 typedef struct {
283 PyObject_HEAD
284 uint64_t kinds;
285 } TypeKindSet;
286
287 typedef struct {
288 PyObject_HEAD
289 uint64_t mask;
290 } TypeKindSetIterator;
291
292 typedef struct {
293 LazyObject lazy_obj;
294 PyObject *name;
295 PyObject *bit_offset;
296 } TypeMember;
297
298 typedef struct {
299 LazyObject lazy_obj;
300 PyObject *name;
301 } TypeParameter;
302
303 typedef struct {
304 LazyObject lazy_obj;
305 PyObject *name;
306 PyObject *is_default;
307 } TypeTemplateParameter;
308
309 extern PyObject *AbsenceReason_class;
310 extern PyObject *Architecture_class;
311 extern PyObject *FindObjectFlags_class;
312 extern PyObject *KmodSearchMethod_class;
313 extern PyObject *ModuleFileStatus_class;
314 extern PyObject *ModuleSectionAddresses_class;
315 extern PyObject *PlatformFlags_class;
316 extern PyObject *PrimitiveType_class;
317 extern PyObject *ProgramFlags_class;
318 extern PyObject *Qualifiers_class;
319 extern PyObject *SupplementaryFileKind_class;
320 extern PyObject *SymbolBinding_class;
321 extern PyObject *SymbolKind_class;
322 extern PyObject *TypeKind_class;
323 extern PyTypeObject DebugInfoOptions_type;
324 extern PyTypeObject DrgnObject_type;
325 extern PyTypeObject DrgnType_type;
326 extern PyTypeObject ExtraModule_type;
327 extern PyTypeObject FaultError_type;
328 extern PyTypeObject Language_type;
329 extern PyTypeObject MainModule_type;
330 extern PyTypeObject MemorySearchIteratorWithBytes_type;
331 extern PyTypeObject MemorySearchIteratorWithInt_type;
332 extern PyTypeObject MemorySearchIteratorWithStr_type;
333 extern PyTypeObject MemorySearchIterator_type;
334 extern PyTypeObject ModuleIteratorWithNew_type;
335 extern PyTypeObject ModuleIterator_type;
336 extern PyTypeObject ModuleSectionAddressesIterator_type;
337 extern PyTypeObject Module_type;
338 extern PyTypeObject ObjectIterator_type;
339 extern PyTypeObject ObjectNotFoundError_type;
340 extern PyTypeObject Platform_type;
341 extern PyTypeObject Program_type;
342 extern PyTypeObject Register_type;
343 extern PyTypeObject RelocatableModule_type;
344 extern PyTypeObject SharedLibraryModule_type;
345 extern PyTypeObject SourceLocationList_type;
346 extern PyObject *SourceLocation_type;
347 extern PyTypeObject StackFrame_type;
348 extern PyTypeObject StackTrace_type;
349 extern PyTypeObject SymbolIndex_type;
350 extern PyTypeObject Symbol_type;
351 extern PyTypeObject ThreadIterator_type;
352 extern PyTypeObject Thread_type;
353 extern PyTypeObject TypeEnumerator_type;
354 extern PyTypeObject TypeKindSetIterator_type;
355 extern PyTypeObject TypeKindSet_type;
356 extern PyTypeObject TypeMember_type;
357 extern PyTypeObject TypeParameter_type;
358 extern PyTypeObject TypeTemplateParameter_type;
359 extern PyTypeObject VdsoModule_type;
360 extern PyObject *MissingDebugInfoError;
361 extern PyObject *ObjectAbsentError;
362 extern PyObject *OutOfBoundsError;
363
364 PyGILState_STATE drgn_initialize_python(bool *success_ret);
365
366 #define drgn_initialize_python_guard(success_ret) \
367 __attribute__((__cleanup__(PyGILState_Releasep), __unused__)) \
368 PyGILState_STATE PP_UNIQUE(gstate) = drgn_initialize_python(success_ret)
369
370 int add_module_constants(PyObject *m);
371 int init_logging(void);
372
373 bool set_drgn_in_python(void);
374 void clear_drgn_in_python(void);
375
376 static inline void drgn_in_python_cleanup(bool *clearp)
377 {
378 if (*clearp)
379 clear_drgn_in_python();
380 }
381
382 #define drgn_in_python_guard() \
383 __attribute__((__cleanup__(drgn_in_python_cleanup), __unused__)) \
384 bool PP_UNIQUE(clear) = set_drgn_in_python()
385
386 struct drgn_error *drgn_error_from_python(void);
387 void *set_drgn_error(struct drgn_error *err);
388 void *set_error_type_name(const char *format,
389 struct drgn_qualified_type qualified_type);
390
391 #define call_tp_alloc(type) ((type *)type##_type.tp_alloc(&type##_type, 0))
392
393 PyObject *MemorySearchIterator_wrap(PyTypeObject *type,
394 struct drgn_memory_search_iterator *it);
395
396 PyObject *Module_wrap(struct drgn_module *module);
397 static inline Program *Module_prog(Module *module)
398 {
399 struct drgn_program *prog = drgn_module_program(module->module);
400 return container_of(prog, Program, prog);
401 }
402
403 int add_WantedSupplementaryFile(PyObject *m);
404 int init_module_section_addresses(void);
405
406 PyObject *Language_wrap(const struct drgn_language *language);
407 int language_converter(PyObject *o, void *p);
408 int add_languages(void);
409
410 PyObject *TypeKindSet_wrap(uint64_t mask);
411 int init_type_kind_set(void);
412
413 static inline DrgnObject *DrgnObject_alloc(Program *prog)
414 {
415 DrgnObject *ret = call_tp_alloc(DrgnObject);
416 if (ret) {
417 drgn_object_init(&ret->obj, &prog->prog);
418 Py_INCREF(prog);
419 }
420 return ret;
421 }
422 static inline Program *DrgnObject_prog(DrgnObject *obj)
423 {
424 return container_of(drgn_object_program(&obj->obj), Program, prog);
425 }
426 PyObject *DrgnObject_NULL(PyObject *self, PyObject *args, PyObject *kwds);
427 DrgnObject *cast(PyObject *self, PyObject *args, PyObject *kwds);
428 DrgnObject *implicit_convert(PyObject *self, PyObject *args, PyObject *kwds);
429 DrgnObject *reinterpret(PyObject *self, PyObject *args, PyObject *kwds);
430 DrgnObject *DrgnObject_container_of(PyObject *self, PyObject *args,
431 PyObject *kwds);
432
433 PyObject *Platform_wrap(const struct drgn_platform *platform);
434
435 int Program_hold_object(Program *prog, PyObject *obj);
436 bool Program_hold_reserve(Program *prog, size_t n);
437 int Program_type_arg(Program *prog, PyObject *type_obj, bool can_be_none,
438 struct drgn_qualified_type *ret);
439 Program *program_from_core_dump(PyObject *self, PyObject *args, PyObject *kwds);
440 Program *program_from_kernel(PyObject *self);
441 Program *program_from_pid(PyObject *self, PyObject *args, PyObject *kwds);
442
443 int add_SourceLocation(PyObject *m);
444 PyObject *SourceLocationList_wrap(struct drgn_source_location_list *locs);
445
446 PyObject *Symbol_wrap(struct drgn_symbol *sym, PyObject *name_obj);
447 PyObject *Symbol_list_wrap(struct drgn_symbol **symbols, size_t count,
448 PyObject *name_obj);
449
450 PyObject *Thread_wrap(struct drgn_thread *drgn_thread);
451
452 PyObject *StackTrace_wrap(struct drgn_stack_trace *trace);
453
454 static inline Program *DrgnType_prog(DrgnType *type)
455 {
456 return container_of(drgn_type_program(type->type), Program, prog);
457 }
458 PyObject *DrgnType_wrap(struct drgn_qualified_type qualified_type);
459 DrgnType *Program_void_type(Program *self, PyObject *args, PyObject *kwds);
460 DrgnType *Program_int_type(Program *self, PyObject *args, PyObject *kwds);
461 DrgnType *Program_bool_type(Program *self, PyObject *args, PyObject *kwds);
462 DrgnType *Program_float_type(Program *self, PyObject *args, PyObject *kwds);
463 DrgnType *Program_struct_type(Program *self, PyObject *args, PyObject *kwds);
464 DrgnType *Program_union_type(Program *self, PyObject *args, PyObject *kwds);
465 DrgnType *Program_class_type(Program *self, PyObject *args, PyObject *kwds);
466 DrgnType *Program_enum_type(Program *self, PyObject *args, PyObject *kwds);
467 DrgnType *Program_typedef_type(Program *self, PyObject *args, PyObject *kwds);
468 DrgnType *Program_pointer_type(Program *self, PyObject *args, PyObject *kwds);
469 DrgnType *Program_array_type(Program *self, PyObject *args, PyObject *kwds);
470 DrgnType *Program_function_type(Program *self, PyObject *args, PyObject *kwds);
471
472 int append_string(PyObject *parts, const char *s);
473 int append_u64_hex(PyObject *parts, uint64_t value);
474 int append_format(PyObject *parts, const char *format, ...);
475 int append_attr_repr(PyObject *parts, PyObject *obj, const char *attr_name);
476 int append_attr_str(PyObject *parts, PyObject *obj, const char *attr_name);
477 PyObject *join_strings(PyObject *parts);
478 // Implementation of _repr_pretty_() for IPython/Jupyter that just calls str().
479 PyObject *repr_pretty_from_str(PyObject *self, PyObject *args, PyObject *kwds);
480
481 struct index_arg {
482 bool allow_none;
483 bool is_none;
484 bool is_signed;
485 union {
486 unsigned long long uvalue;
487 long long svalue;
488 };
489 };
490 int index_converter(PyObject *o, void *p);
491
492 int u64_converter(PyObject *o, void *p);
493
494 struct path_arg {
495 bool allow_fd;
496 bool allow_none;
497 int fd;
498 char *path;
499 Py_ssize_t length;
500 PyObject *object;
501 PyObject *bytes;
502 };
503 int path_converter(PyObject *o, void *p);
504 void path_cleanup(struct path_arg *path);
505
506 #define PATH_ARG(name, ...) \
507 __attribute__((__cleanup__(path_cleanup))) \
508 struct path_arg name = { __VA_ARGS__ }
509
510 DEFINE_VECTOR_TYPE(path_arg_vector, struct path_arg);
511
512 struct path_sequence_arg {
513 bool allow_none;
514 bool null_terminate;
515 struct path_arg_vector args;
516 const char **paths;
517 };
518 int path_sequence_converter(PyObject *o, void *p);
519 void path_sequence_cleanup(struct path_sequence_arg *paths);
520 size_t path_sequence_size(struct path_sequence_arg *paths);
521
522 #define PATH_SEQUENCE_ARG(name, ...) \
523 __attribute__((__cleanup__(path_sequence_cleanup))) \
524 struct path_sequence_arg name = { .args = VECTOR_INIT, __VA_ARGS__ }
525
526 struct enum_arg {
527 PyObject *type;
528 unsigned long value;
529 bool allow_none;
530 };
531 int enum_converter(PyObject *o, void *p);
532
533 PyObject *drgnpy_linux_helper_direct_mapping_offset(PyObject *self,
534 PyObject *arg);
535 PyObject *drgnpy_linux_helper_read_vm(PyObject *self, PyObject *args,
536 PyObject *kwds);
537 PyObject *drgnpy_linux_helper_follow_phys(PyObject *self, PyObject *args,
538 PyObject *kwds);
539 DrgnObject *drgnpy_linux_helper_per_cpu_ptr(PyObject *self, PyObject *args,
540 PyObject *kwds);
541 DrgnObject *drgnpy_linux_helper_cpu_curr(PyObject *self, PyObject *args);
542 DrgnObject *drgnpy_linux_helper_idle_task(PyObject *self, PyObject *args);
543 DrgnObject *drgnpy_linux_helper_task_thread_info(PyObject *self, PyObject *args,
544 PyObject *kwds);
545 PyObject *drgnpy_linux_helper_task_cpu(PyObject *self, PyObject *args,
546 PyObject *kwds);
547 PyObject *drgnpy_linux_helper_task_on_cpu(PyObject *self, PyObject *args,
548 PyObject *kwds);
549 DrgnObject *drgnpy_linux_helper_xa_load(PyObject *self, PyObject *args,
550 PyObject *kwds);
551 DrgnObject *drgnpy_linux_helper_idr_find(PyObject *self, PyObject *args,
552 PyObject *kwds);
553 DrgnObject *drgnpy_linux_helper_find_pid(PyObject *self, PyObject *args);
554 DrgnObject *drgnpy_linux_helper_pid_task(PyObject *self, PyObject *args,
555 PyObject *kwds);
556 DrgnObject *drgnpy_linux_helper_find_task(PyObject *self, PyObject *args);
557 PyObject *drgnpy_linux_helper_kaslr_offset(PyObject *self, PyObject *arg);
558 PyObject *drgnpy_linux_helper_pgtable_l5_enabled(PyObject *self, PyObject *arg);
559 PyObject *drgnpy_linux_helper_load_proc_kallsyms(PyObject *self, PyObject *args,
560 PyObject *kwds);
561 PyObject *drgnpy_linux_helper_load_builtin_kallsyms(PyObject *self, PyObject *args,
562 PyObject *kwds);
563
564 #endif /* DRGNPY_H */