1 /*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21 /*
22 * Copyright 2010 Sun Microsystems, Inc. All rights reserved.
23 * Use is subject to license terms.
24 */
25
26 #include <mdb/mdb_modapi.h>
27
28 #include <pthread.h>
29 #include <stddef.h>
30 #include <dlfcn.h>
31 #include <link.h>
32 #include <libproc.h>
33
34 #include <Python.h>
35 #include <frameobject.h>
36
37 /*
38 * Decoding Python Stack Frames
39 * ============================
40 *
41 * Python2 uses a variety of objects to construct its call chain. An address
42 * space may have one or more PyInterpreterState objects, which are the base
43 * object in the interpreter's state. These objects are kept in a linked list
44 * with a head pointer named interp_head. This makes it possible for the
45 * debugger to get a toehold on data structures necessary to understand the
46 * interpreter. Since most of these structures are linked out of the
47 * InterpreterState, traversals generally start here.
48 *
49 * In order to decode a frame, the debugger needs to walk from
50 * PyInterpreterState down to a PyCodeObject. The diagram below shows the
51 * the objects that must be examined in order to reach a leaf PyCodeObject.
52 *
53 * +--------------------+ next +--------------------+ next
54 * interp_head -> | PyInterpreterState | ----> | PyInterpreterState | ---> ...
55 * +--------------------+ +--------------------+
56 * | | tstate_head
57 * | tstate_head V
58 * | +---------------+ frame
59 * V | PyThreadState | -----> ...
60 * +---------------+ frame +---------------+
61 * | PyThreadState | ---> ...
62 * +---------------+
63 * | next
64 * V
65 * +---------------+ frame +---------------+ f_back +---------------+
66 * | PyThreadState | ------> | PyFrameObject | -----> | PyFrameObject |
67 * +---------------+ +---------------+ +---------------+
68 * | |
69 * | f_code | f_code
70 * V V
71 * +--------------+ ...
72 * | PyCodeObject |
73 * +--------------+
74 * co_filename | | | co_lnotab
75 * +-------------+ | +-------------+
76 * | co_name | |
77 * V V V
78 * +----------------+ +----------------+ +----------------+
79 * | PyStringObject | | PyStringObject | | PyStringObject |
80 * +----------------+ +----------------+ +----------------+
81 *
82 * The interp_head pointer is a list of one or more PyInterpreterState
83 * objects. Each of these objects can contain one or more PyThreadState
84 * objects. The PyInterpreterState object keeps a pointer to the head of the
85 * list of PyThreadState objects as tstate_head.
86 *
87 * Each thread keeps ahold of its stack frames. The PyThreadState object
88 * has a pointer to the topmost PyFrameObject, kept in frame. The
89 * successive frames on the stack are kept linked in the PyFrameObject's
90 * f_back pointer, with each frame pointing to its caller.
91 *
92 * In order to decode each call frame, our code needs to look at the
93 * PyCodeObject for each frame. Essentially, this is the code that is
94 * being executed in the frame. The PyFrameObject keeps a pointer to this
95 * code object in f_code. In order to print meaningful debug information,
96 * it's necessary to extract the Python filename (co_filename), the
97 * function name (co_name), and the line number within the file
98 * (co_lnotab). The filename and function are stored as strings, but the
99 * line number is a mapping of bytecode offsets to line numbers. The
100 * description of the lnotab algorithm lives here:
101 *
102 * http://svn.python.org/projects/python/trunk/Objects/lnotab_notes.txt
103 *
104 * In order to decode the frame, the debugger needs to walk each
105 * InterpreterState object. For each InterpreterState, every PyThreadState
106 * must be traversed. The PyThreadState objects point to the
107 * PyFrameObjects. For every thread, we must walk the frames backwards and
108 * decode the strings that are in the PyCodeObjects.
109 */
110
111 /*
112 * The Python-dependent debugging functionality lives in its own helper
113 * library. The helper agent is provided by libpython2.[67]_db.so, which
114 * is also used by pstack(1) for debugging Python processes.
115 *
116 * Define needed prototypes here.
117 */
118
119 #define PYDB_VERSION 1
120 typedef struct pydb_agent pydb_agent_t;
121 typedef struct pydb_iter pydb_iter_t;
122
123 typedef pydb_agent_t *(*pydb_agent_create_f)(struct ps_prochandle *P, int vers);
124 typedef void (*pydb_agent_destroy_f)(pydb_agent_t *py);
125 typedef int (*pydb_get_frameinfo_f)(pydb_agent_t *py, uintptr_t frame_addr,
126 char *fbuf, size_t bufsz, int verbose);
127 typedef pydb_iter_t *(*pydb_iter_init_f)(pydb_agent_t *py, uintptr_t addr);
128 typedef uintptr_t (*pydb_iter_next_f)(pydb_iter_t *iter);
129 typedef void (*pydb_iter_fini_f)(pydb_iter_t *iter);
130
131 static pydb_agent_create_f pydb_agent_create;
132 static pydb_agent_destroy_f pydb_agent_destroy;
133 static pydb_get_frameinfo_f pydb_get_frameinfo;
134 static pydb_iter_init_f pydb_frame_iter_init;
135 static pydb_iter_init_f pydb_interp_iter_init;
136 static pydb_iter_init_f pydb_thread_iter_init;
137 static pydb_iter_next_f pydb_iter_next;
138 static pydb_iter_fini_f pydb_iter_fini;
139
140 static pydb_agent_t *pydb_hdl = NULL;
141 static void *pydb_dlhdl = NULL;
142
143 /*ARGSUSED*/
144 static int
py_frame(uintptr_t addr,uint_t flags,int argc,const mdb_arg_t * argv)145 py_frame(uintptr_t addr, uint_t flags, int argc, const mdb_arg_t *argv)
146 {
147 char buf[1024];
148 int verbose = FALSE;
149
150 if (mdb_getopts(argc, argv,
151 'v', MDB_OPT_SETBITS, TRUE, &verbose,
152 NULL) != argc) {
153 return (DCMD_USAGE);
154 }
155
156 if (flags & DCMD_PIPE_OUT) {
157 mdb_warn("py_stack cannot output into a pipe\n");
158 return (DCMD_ERR);
159 }
160
161 if (!(flags & DCMD_ADDRSPEC)) {
162 mdb_warn("no address");
163 return (DCMD_USAGE);
164 }
165
166 if (pydb_get_frameinfo(pydb_hdl, addr, buf, sizeof (buf),
167 verbose) < 0) {
168 mdb_warn("Unable to find frame at address %p\n", addr);
169 return (DCMD_ERR);
170 }
171
172 mdb_printf("%s", buf);
173
174 return (DCMD_OK);
175 }
176
177 int
py_interp_walk_init(mdb_walk_state_t * wsp)178 py_interp_walk_init(mdb_walk_state_t *wsp)
179 {
180 pydb_iter_t *pdi;
181
182 pdi = pydb_interp_iter_init(pydb_hdl, wsp->walk_addr);
183
184 if (pdi == NULL) {
185 mdb_warn("unable to create interpreter iterator\n");
186 return (DCMD_ERR);
187 }
188
189 wsp->walk_data = pdi;
190
191 return (WALK_NEXT);
192 }
193
194 int
py_walk_step(mdb_walk_state_t * wsp)195 py_walk_step(mdb_walk_state_t *wsp)
196 {
197 pydb_iter_t *pdi = wsp->walk_data;
198 uintptr_t addr;
199 int status;
200
201 addr = pydb_iter_next(pdi);
202
203 if (addr == 0) {
204 return (WALK_DONE);
205 }
206
207 status = wsp->walk_callback(addr, 0, wsp->walk_cbdata);
208
209 return (status);
210 }
211
212 void
py_walk_fini(mdb_walk_state_t * wsp)213 py_walk_fini(mdb_walk_state_t *wsp)
214 {
215 pydb_iter_t *pdi = wsp->walk_data;
216 pydb_iter_fini(pdi);
217 }
218
219 int
py_thread_walk_init(mdb_walk_state_t * wsp)220 py_thread_walk_init(mdb_walk_state_t *wsp)
221 {
222 pydb_iter_t *pdi;
223
224 pdi = pydb_thread_iter_init(pydb_hdl, wsp->walk_addr);
225 if (pdi == NULL) {
226 mdb_warn("unable to create thread iterator\n");
227 return (DCMD_ERR);
228 }
229
230 wsp->walk_data = pdi;
231
232 return (WALK_NEXT);
233 }
234
235 int
py_frame_walk_init(mdb_walk_state_t * wsp)236 py_frame_walk_init(mdb_walk_state_t *wsp)
237 {
238 pydb_iter_t *pdi;
239
240 pdi = pydb_frame_iter_init(pydb_hdl, wsp->walk_addr);
241 if (pdi == NULL) {
242 mdb_warn("unable to create frame iterator\n");
243 return (DCMD_ERR);
244 }
245
246 wsp->walk_data = pdi;
247
248 return (WALK_NEXT);
249 }
250
251 /*ARGSUSED*/
252 static int
python_stack(uintptr_t addr,const PyThreadState * ts,uint_t * verbose)253 python_stack(uintptr_t addr, const PyThreadState *ts, uint_t *verbose)
254 {
255 mdb_arg_t nargv;
256 uint_t nargc = (verbose != NULL && *verbose) ? 1 : 0;
257 /*
258 * Pass the ThreadState to the frame walker. Have frame walker
259 * call frame dcmd.
260 */
261 mdb_printf("PyThreadState: %0?p\n", addr);
262
263 nargv.a_type = MDB_TYPE_STRING;
264 nargv.a_un.a_str = "-v";
265
266 if (mdb_pwalk_dcmd("pyframe", "pyframe", nargc, &nargv, addr) == -1) {
267 mdb_warn("can't walk 'pyframe'");
268 return (WALK_ERR);
269 }
270
271 return (WALK_NEXT);
272 }
273
274 /*ARGSUSED*/
275 static int
python_thread(uintptr_t addr,const PyInterpreterState * is,uint_t * verbose)276 python_thread(uintptr_t addr, const PyInterpreterState *is, uint_t *verbose)
277 {
278 /*
279 * Pass the InterpreterState to the threadstate walker.
280 */
281 if (mdb_pwalk("pythread", (mdb_walk_cb_t)python_stack, verbose,
282 addr) == -1) {
283 mdb_warn("can't walk 'pythread'");
284 return (WALK_ERR);
285 }
286
287 return (WALK_NEXT);
288 }
289
290 /*ARGSUSED*/
291 static int
py_stack(uintptr_t addr,uint_t flags,int argc,const mdb_arg_t * argv)292 py_stack(uintptr_t addr, uint_t flags, int argc, const mdb_arg_t *argv)
293 {
294 uint_t verbose = FALSE;
295
296 if (mdb_getopts(argc, argv,
297 'v', MDB_OPT_SETBITS, TRUE, &verbose,
298 NULL) != argc)
299 return (DCMD_USAGE);
300
301 if (flags & DCMD_PIPE_OUT) {
302 mdb_warn("py_stack cannot output into a pipe\n");
303 return (DCMD_ERR);
304 }
305
306 if (flags & DCMD_ADDRSPEC) {
307 mdb_arg_t nargv;
308 uint_t nargc = verbose ? 1 : 0;
309
310 nargv.a_type = MDB_TYPE_STRING;
311 nargv.a_un.a_str = "-v";
312
313 if (mdb_pwalk_dcmd("pyframe", "pyframe", nargc, &nargv, addr)
314 == -1) {
315 mdb_warn("can't walk 'pyframe'");
316 return (DCMD_ERR);
317 }
318 return (DCMD_OK);
319 }
320
321 if (mdb_walk("pyinterp", (mdb_walk_cb_t)python_thread,
322 &verbose) == -1) {
323 mdb_warn("can't walk 'pyinterp'");
324 return (DCMD_ERR);
325 }
326
327 return (DCMD_OK);
328 }
329
330 static const mdb_dcmd_t dcmds[] = {
331 { "pystack", "[-v]", "print python stacks", py_stack },
332 { "pyframe", "[-v]", "print python frames", py_frame },
333 { NULL }
334 };
335
336 static const mdb_walker_t walkers[] = {
337 { "pyinterp", "walk python interpreter structures",
338 py_interp_walk_init, py_walk_step, py_walk_fini },
339 { "pythread", "given an interpreter, walk the list of python threads",
340 py_thread_walk_init, py_walk_step, py_walk_fini },
341 { "pyframe", "given a thread state, walk the list of frame objects",
342 py_frame_walk_init, py_walk_step, py_walk_fini },
343 { NULL }
344 };
345
346 static const mdb_modinfo_t modinfo = {
347 MDB_API_VERSION, dcmds, walkers
348 };
349
350 /*ARGSUSED*/
351 static int
python_object_iter(void * cd,const prmap_t * pmp,const char * obj)352 python_object_iter(void *cd, const prmap_t *pmp, const char *obj)
353 {
354 char path[PATH_MAX];
355 char *name;
356 char *s1, *s2;
357 struct ps_prochandle *Pr = cd;
358
359 name = strstr(obj, "/libpython");
360
361 if (name) {
362 (void) strcpy(path, obj);
363 if (Pstatus(Pr)->pr_dmodel != PR_MODEL_NATIVE) {
364 s1 = name;
365 s2 = path + (s1 - obj);
366 (void) strcpy(s2, "/64");
367 s2 += 3;
368 (void) strcpy(s2, s1);
369 }
370
371 s1 = strstr(obj, ".so");
372 s2 = strstr(path, ".so");
373 (void) strcpy(s2, "_db");
374 s2 += 3;
375 (void) strcpy(s2, s1);
376
377 if ((pydb_dlhdl = dlopen(path, RTLD_LAZY|RTLD_GLOBAL)) != NULL)
378 return (1);
379 }
380
381 return (0);
382 }
383
384 static int
python_db_init(void)385 python_db_init(void)
386 {
387 struct ps_prochandle *Ph;
388
389 if (mdb_get_xdata("pshandle", &Ph, sizeof (Ph)) == -1) {
390 mdb_warn("couldn't read pshandle xdata\n");
391 dlclose(pydb_dlhdl);
392 pydb_dlhdl = NULL;
393 return (-1);
394 }
395
396 (void) Pobject_iter(Ph, python_object_iter, Ph);
397
398 pydb_agent_create = (pydb_agent_create_f)
399 dlsym(pydb_dlhdl, "pydb_agent_create");
400 pydb_agent_destroy = (pydb_agent_destroy_f)
401 dlsym(pydb_dlhdl, "pydb_agent_destroy");
402 pydb_get_frameinfo = (pydb_get_frameinfo_f)
403 dlsym(pydb_dlhdl, "pydb_get_frameinfo");
404
405 pydb_frame_iter_init = (pydb_iter_init_f)
406 dlsym(pydb_dlhdl, "pydb_frame_iter_init");
407 pydb_interp_iter_init = (pydb_iter_init_f)
408 dlsym(pydb_dlhdl, "pydb_interp_iter_init");
409 pydb_thread_iter_init = (pydb_iter_init_f)
410 dlsym(pydb_dlhdl, "pydb_thread_iter_init");
411 pydb_iter_next = (pydb_iter_next_f)dlsym(pydb_dlhdl, "pydb_iter_next");
412 pydb_iter_fini = (pydb_iter_fini_f)dlsym(pydb_dlhdl, "pydb_iter_fini");
413
414
415 if (pydb_agent_create == NULL || pydb_agent_destroy == NULL ||
416 pydb_get_frameinfo == NULL || pydb_frame_iter_init == NULL ||
417 pydb_interp_iter_init == NULL || pydb_thread_iter_init == NULL ||
418 pydb_iter_next == NULL || pydb_iter_fini == NULL) {
419 mdb_warn("couldn't load pydb functions");
420 dlclose(pydb_dlhdl);
421 pydb_dlhdl = NULL;
422 return (-1);
423 }
424
425 pydb_hdl = pydb_agent_create(Ph, PYDB_VERSION);
426 if (pydb_hdl == NULL) {
427 mdb_warn("unable to create pydb_agent");
428 dlclose(pydb_dlhdl);
429 pydb_dlhdl = NULL;
430 return (-1);
431 }
432
433 return (0);
434 }
435
436 static void
python_db_fini(void)437 python_db_fini(void)
438 {
439 if (pydb_dlhdl) {
440 pydb_agent_destroy(pydb_hdl);
441 pydb_hdl = NULL;
442
443 dlclose(pydb_dlhdl);
444 pydb_dlhdl = NULL;
445 }
446 }
447
448 const mdb_modinfo_t *
_mdb_init(void)449 _mdb_init(void)
450 {
451 if (python_db_init() != 0)
452 return (NULL);
453
454 return (&modinfo);
455 }
456
457 void
_mdb_fini(void)458 _mdb_fini(void)
459 {
460 python_db_fini();
461 }
462