Update NEWS
[platform/upstream/ltrace.git] / backend.h
1 /*
2  * This file is part of ltrace.
3  * Copyright (C) 2012,2013 Petr Machata, Red Hat Inc.
4  *
5  * This program is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU General Public License as
7  * published by the Free Software Foundation; either version 2 of the
8  * License, or (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful, but
11  * WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
18  * 02110-1301 USA
19  */
20
21 #ifndef BACKEND_H
22 #define BACKEND_H
23
24 #include "forward.h"
25 #include "sysdep.h"
26
27 #include <gelf.h>
28
29 enum process_status {
30         PS_INVALID,     /* Failure.  */
31         PS_STOP,        /* Job-control stop.  */
32         PS_TRACING_STOP,
33         PS_SLEEPING,
34         PS_ZOMBIE,
35         PS_OTHER,       /* Necessary other states can be added as needed.  */
36 };
37
38 /*
39  * This file contains documentation of back end interface.  Some of
40  * these may be implemented on an OS level (i.e. they are the same
41  * e.g. on all Linux architectures), some may differ per architecture
42  * on the same OS (e.g. a way to insert a breakpoint into the process
43  * image is a likely candidate).
44  */
45
46 /* Convert a PID to a path to the corresponding binary.  */
47 char *pid2name(pid_t pid);
48
49 /* Given a PID, find a leader of thread group.  */
50 pid_t process_leader(pid_t pid);
51
52 /* Given a PID of leader thread, fill in PIDs of all the tasks.  The
53  * function will initialize the pointer *RET_TASKS to a
54  * newly-allocated array, and will store number of elements in that
55  * array to *RET_N.  You have to free that buffer when you don't need
56  * it anymore.  */
57 int process_tasks(pid_t pid, pid_t **ret_tasks, size_t *ret_n);
58
59 /* Answer whether the process PID is stopped.  Returns 0 when not
60  * stopped, 1 when stopped, or -1 when there was an error.  */
61 int process_stopped(pid_t pid);
62
63 /* Answer a status of the task PID.  See enum process_status.  */
64 enum process_status process_status(pid_t pid);
65
66 /* Wait for PID to be ready for tracing.  */
67 int wait_for_proc(pid_t pid);
68
69 /* Send a signal SIG to the task PID.  */
70 int task_kill(pid_t pid, int sig);
71
72 /* Called after PID is attached, but before it is continued.  */
73 void trace_set_options(struct process *proc);
74
75 /* Called after ltrace forks.  Should attach the newly created child,
76  * in whose context this function is called.  */
77 void trace_me(void);
78
79 /* Called when ltrace needs to attach to PID, such as when it attaches
80  * to a running process, whose PID is given on the command line.  */
81 int trace_pid(pid_t pid);
82
83 /* Stop tracing PID.  */
84 void untrace_pid(pid_t pid);
85
86 /* The back end may need to store arbitrary data to a process.  This
87  * is a place where it can initialize PROC->arch_dep.  XXX this should
88  * be dropped in favor of arhc_process_init on pmachata/libs.  */
89 void get_arch_dep(struct process *proc);
90
91 /* Return current instruction pointer of PROC.
92  *
93  * XXX note that the IP must fit into an arch pointer.  This prevents
94  * us to use 32-bit ltrace to trace 64-bit process, even on arches
95  * that would otherwise support this.  Above we have a definition of
96  * arch_addr_t.  This should be converted to an integral type and
97  * used for target addresses throughout.  */
98 void *get_instruction_pointer(struct process *proc);
99
100 /* Set instruction pointer of PROC to ADDR.  XXX see above.  */
101 void set_instruction_pointer(struct process *proc, void *addr);
102
103 /* Return current stack pointer of PROC.  XXX see above.  */
104 void *get_stack_pointer(struct process *proc);
105
106 /* Find and return caller address, i.e. the address where the current
107  * function returns.  */
108 void *get_return_addr(struct process *proc, void *stack_pointer);
109
110 /* Enable breakpoint SBP in process PROC.  */
111 void enable_breakpoint(struct process *proc, struct breakpoint *sbp);
112
113 /* Disable breakpoint SBP in process PROC.  */
114 void disable_breakpoint(struct process *proc, struct breakpoint *sbp);
115
116 /* Determine whether the event that we have just seen (and that is
117  * recorded in STATUS) was a syscall.  If it was, return 1.  If it was
118  * a return from syscall, return 2.  In both cases, set *SYSNUM to the
119  * number of said syscall.  If it wasn't a syscall, return 0.  If
120  * there was an error, return -1.  */
121 int syscall_p(struct process *proc, int status, int *sysnum);
122
123 /* Continue execution of the process with given PID.  */
124 void continue_process(pid_t pid);
125
126 /* Called after we received a signal SIGNUM.  Should do whatever
127  * book-keeping is necessary and continue the process if
128  * necessary.  */
129 void continue_after_signal(pid_t pid, int signum);
130
131 /* Called after we received a system call SYSNUM.  RET_P is 0 if this
132  * is system call, otherwise it's return from a system call.  The
133  * callback should do whatever book-keeping is necessary and continue
134  * the process if necessary.  */
135 void continue_after_syscall(struct process *proc, int sysnum, int ret_p);
136
137 /* Called after we hit a breakpoint SBP.  Should do whatever
138  * book-keeping is necessary and then continue the process.  */
139 void continue_after_breakpoint(struct process *proc, struct breakpoint *sbp);
140
141 /* Called after we received a vfork.  Should do whatever book-keeping
142  * is necessary and continue the process if necessary.  N.B. right
143  * now, with Linux/GNU the only back end, this is not necessary.  I
144  * imagine other systems may be different.  */
145 void continue_after_vfork(struct process *proc);
146
147 /* Called after the process exec's.  Should do whatever book-keeping
148  * is necessary and then continue the process.  */
149 void continue_after_exec(struct process *proc);
150
151 /* Called when trace_me or primary trace_pid fail.  This may plug in
152  * any platform-specific knowledge of why it could be so.  */
153 void trace_fail_warning(pid_t pid);
154
155 /* A pair of functions called to initiate a detachment request when
156  * ltrace is about to exit.  Their job is to undo any effects that
157  * tracing had and eventually detach process, perhaps by way of
158  * installing a process handler.
159  *
160  * OS_LTRACE_EXITING_SIGHANDLER is called from a signal handler
161  * context right after the signal was captured.  It returns 1 if the
162  * request was handled or 0 if it wasn't.
163  *
164  * If the call to OS_LTRACE_EXITING_SIGHANDLER didn't handle the
165  * request, OS_LTRACE_EXITING is called when the next event is
166  * generated.  Therefore it's called in "safe" context, without
167  * re-entrancy concerns, but it's only called after an even is
168  * generated.  */
169 int os_ltrace_exiting_sighandler(void);
170 void os_ltrace_exiting(void);
171
172 /* Should copy COUNT bytes from address ADDR of process PROC to local
173  * buffer BUF.  */
174 size_t umovebytes(struct process *proc, void *addr, void *buf, size_t count);
175
176 /* Find out an address of symbol SYM in process PROC, and return.
177  * Returning NULL delays breakpoint insertion and enables heaps of
178  * arch-specific black magic that we should clean up some day.
179  *
180  * XXX the same points as for get_instruction_pointer apply. */
181 void *sym2addr(struct process *proc, struct library_symbol *sym);
182
183 /* Obtain address of PLT entry corresponding to relocation RELA in
184  * file LTE.  This is NDX-th PLT entry in the file.
185  *
186  * XXX should this return arch_addr_t?  */
187 GElf_Addr arch_plt_sym_val(struct ltelf *lte, size_t ndx, GElf_Rela *rela);
188
189 /* Called at some point after we have attached to PROC.  This callback
190  * should insert an introspection breakpoint for handling dynamic
191  * linker library loads.  */
192 int linkmap_init(struct process *proc, arch_addr_t dyn_addr);
193
194 /* This should produce and return the next event of one of the traced
195  * processes.  The returned pointer will not be freed by the core and
196  * should be either statically allocated, or the management should be
197  * done some other way.  */
198 struct Event *next_event(void);
199
200 /* Called when process PROC was removed.  */
201 void process_removed(struct process *proc);
202
203 /* This should extract entry point address and interpreter (dynamic
204  * linker) bias if possible.  Returns 0 if there were no errors, -1
205  * otherwise.  Sets *ENTRYP and *INTERP_BIASP to non-zero values if
206  * the corresponding value is known, or zero otherwise; this is not
207  * done for pointers that are NULL.  */
208 int process_get_entry(struct process *proc,
209                       arch_addr_t *entryp,
210                       arch_addr_t *interp_biasp);
211
212 \f
213 /* Optional callbacks
214  *
215  * Some callbacks are only available if backend (arch.h) has a certain
216  * define.  If such a define is not present, default implementation
217  * (most often doing nothing at all) us used instead.  This is used
218  * for gradual extensions of ltrace, so that backends that are not
219  * fully up to date, or that don't need certain functionality, keep
220  * working, while other backends take advantage of the optional
221  * features.  */
222
223 /* The following callbacks have to be implemented in backend if arch.h
224  * defines ARCH_HAVE_LTELF_DATA.  Those are used to init and destroy
225  * LTE->arch.  arch_elf_init returns 0 on success or a negative value
226  * on failure.  */
227 int arch_elf_init(struct ltelf *lte, struct library *lib);
228 void arch_elf_destroy(struct ltelf *lte);
229
230 /* The following callbacks have to be implemented in OS backend if
231  * os.h defines OS_HAVE_BREAKPOINT_DATA.  Those are used to init,
232  * destroy, and clone SBP->os.  os_breakpoint_init and
233  * os_breakpoint_clone return 0 on success or a negative value on
234  * failure.  */
235 int os_breakpoint_init(struct process *proc, struct breakpoint *sbp);
236 void os_breakpoint_destroy(struct breakpoint *sbp);
237 int os_breakpoint_clone(struct breakpoint *retp, struct breakpoint *sbp);
238
239 /* The following callbacks have to be implemented in backend if arch.h
240  * defines ARCH_HAVE_BREAKPOINT_DATA.  Those are used to init,
241  * destroy, and clone SBP->arch.  arch_breakpoint_init and
242  * arch_breakpoint_clone return 0 on success or a negative value on
243  * failure.  */
244 int arch_breakpoint_init(struct process *proc, struct breakpoint *sbp);
245 void arch_breakpoint_destroy(struct breakpoint *sbp);
246 int arch_breakpoint_clone(struct breakpoint *retp, struct breakpoint *sbp);
247
248 /* The following callbacks have to be implemented in OS backend if
249  * os.h defines OS_HAVE_LIBRARY_DATA.  Those are used to init, destroy
250  * and clone LIB->os.  os_library_init and os_library_clone return 0
251  * on success or a negative value on failure.  */
252 int os_library_init(struct library *lib);
253 void os_library_destroy(struct library *lib);
254 int os_library_clone(struct library *retp, struct library *lib);
255
256 /* The following callbacks have to be implemented in backend if arch.h
257  * defines ARCH_HAVE_LIBRARY_DATA.  Those are used to init, destroy
258  * and clone LIB->arch.  arch_library_init and arch_library_clone
259  * return 0 on success or a negative value on failure.  */
260 int arch_library_init(struct library *lib);
261 void arch_library_destroy(struct library *lib);
262 int arch_library_clone(struct library *retp, struct library *lib);
263
264 /* The following callbacks have to be implemented in OS backend if
265  * os.h defines OS_HAVE_LIBRARY_SYMBOL_DATA.  Those are used to init,
266  * destroy and clone LIBSYM->os.  os_library_symbol_init and
267  * os_library_symbol_clone return 0 on success or a negative value on
268  * failure.  */
269 int os_library_symbol_init(struct library_symbol *libsym);
270 void os_library_symbol_destroy(struct library_symbol *libsym);
271 int os_library_symbol_clone(struct library_symbol *retp,
272                             struct library_symbol *libsym);
273
274 /* The following callbacks have to be implemented in backend if arch.h
275  * defines ARCH_HAVE_LIBRARY_SYMBOL_DATA.  Those are used to init,
276  * destroy and clone LIBSYM->arch.  arch_library_symbol_init and
277  * arch_library_symbol_clone return 0 on success or a negative value
278  * on failure.  */
279 int arch_library_symbol_init(struct library_symbol *libsym);
280 void arch_library_symbol_destroy(struct library_symbol *libsym);
281 int arch_library_symbol_clone(struct library_symbol *retp,
282                               struct library_symbol *libsym);
283
284 /* The following callbacks have to be implemented in OS backend if
285  * os.h defines OS_HAVE_PROCESS_DATA.  The protocol is same as for,
286  * respectively, arch_process_init, arch_process_destroy,
287  * arch_process_clone and arch_process_exec.  */
288 int os_process_init(struct process *proc);
289 void os_process_destroy(struct process *proc);
290 int os_process_clone(struct process *retp, struct process *proc);
291 int os_process_exec(struct process *proc);
292
293 /* The following callbacks have to be implemented in backend if arch.h
294  * defines ARCH_HAVE_PROCESS_DATA.  Those are used to init, destroy
295  * and clone PROC->arch.  arch_process_exec is called to update
296  * PROC->arch in case that PROC underwent an exec.  See notes at
297  * process_init, process_destroy, process_clone and process_exec in
298  * proc.h.  */
299 int arch_process_init(struct process *proc);
300 void arch_process_destroy(struct process *proc);
301 int arch_process_clone(struct process *retp, struct process *proc);
302 int arch_process_exec(struct process *proc);
303
304 /* The following callback has to be implemented in backend if arch.h
305  * defines ARCH_HAVE_GET_SYM_INFO.
306  *
307  * This is called for every PLT relocation RELA in ELF file LTE (which
308  * is named FILENAME), that ltrace is about to add.  The corresponding
309  * PLT entry is for SYM_INDEX-th relocation in the file.  This call is
310  * supposed to initialize SYM and RELA.  It returns 0 if there were no
311  * errors and given symbol should be used, 1 if the symbol should not
312  * be used, or a negative value if there were errors.  */
313 int arch_get_sym_info(struct ltelf *lte, const char *filename, size_t sym_index,
314                       GElf_Rela *rela, GElf_Sym *sym);
315
316 enum plt_status {
317         PLT_FAIL,
318         PLT_OK,
319         PLT_DEFAULT,
320 };
321
322 /* The following callback has to be implemented in OS backend if os.h
323  * defines OS_HAVE_ADD_PLT_ENTRY.
324  *
325  * This is called for every PLT relocation R in ELF file LTE, that
326  * ltrace is about to add to a library constructed in process PROC.
327  * The corresponding PLT entry is for symbol called NAME, and it's
328  * I-th relocation in the file.
329  *
330  * If this function returns PLT_DEFAULT, PLT address is obtained by
331  * calling arch_plt_sym_val, and symbol is allocated.  If PLT_OK or
332  * PLT_DEFAULT are returned, the chain of symbols passed back in RET
333  * is added to library under construction.  */
334 enum plt_status os_elf_add_plt_entry(struct process *proc, struct ltelf *lte,
335                                      const char *name, GElf_Rela *rela,
336                                      size_t i, struct library_symbol **ret);
337
338 /* Like os_elf_add_plt_entry, but tied to ARCH_HAVE_ADD_PLT_ENTRY in
339  * arch.h.  The arch callback is called first.  If it returns
340  * PLT_DEFAULT, the os callback is called next.  */
341 enum plt_status arch_elf_add_plt_entry(struct process *proc, struct ltelf *lte,
342                                        const char *name, GElf_Rela *rela,
343                                        size_t i, struct library_symbol **ret);
344
345 /* The following callback has to be implemented in OS backend if os.h
346  * defines OS_HAVE_ADD_FUNC_ENTRY.
347  *
348  * This is called for every symbol in ltrace is about to add to the
349  * library constructed for LTE in process PROC.
350  *
351  * If this function returns PLT_DEFAULT, then if there is a
352  * pre-existing symbol, its name may be updated if the newly-found
353  * name is shorter.  Otherwise a new symbol is created.
354  *
355  * If PLT_OK or PLT_DEFAULT are returned, the chain of symbols passed
356  * back in RET is added to library under construction.  */
357 enum plt_status os_elf_add_func_entry(struct process *proc, struct ltelf *lte,
358                                       const GElf_Sym *sym,
359                                       arch_addr_t addr, const char *name,
360                                       struct library_symbol **ret);
361
362 /* Like os_elf_add_func_entry, but tied to ARCH_HAVE_ADD_FUNC_ENTRY in
363  * arch.h.  The arch callback is called first.  If it returns
364  * PLT_DEFAULT, the os callback is called next.  */
365 enum plt_status arch_elf_add_func_entry(struct process *proc, struct ltelf *lte,
366                                         const GElf_Sym *sym,
367                                         arch_addr_t addr, const char *name,
368                                         struct library_symbol **ret);
369
370 /* This callback needs to be implemented if arch.h defines
371  * ARCH_HAVE_DYNLINK_DONE.  It is called after the dynamic linker is
372  * done with the process start-up.  */
373 void arch_dynlink_done(struct process *proc);
374
375 /* This callback needs to be implemented if arch.h defines
376  * ARCH_HAVE_SYMBOL_RET.  It is called after a traced call returns.  */
377 void arch_symbol_ret(struct process *proc, struct library_symbol *libsym);
378
379
380 /* This callback needs to be implemented if arch.h defines
381  * ARCH_HAVE_FIND_DL_DEBUG.
382  * It is called by generic code to find the address of the dynamic
383  * linkers debug structure.
384  * DYN_ADDR holds the address of the dynamic section.
385  * If the debug area is found, return 0 and fill in the address in *RET.
386  * If the debug area is not found, return a negative value.  */
387 int arch_find_dl_debug(struct process *proc, arch_addr_t dyn_addr,
388                        arch_addr_t *ret);
389
390 /* This is called to obtain a list of directories to search when
391  * loading config files.  The callback sets *RETP to a pointer to the
392  * first element of a NULL-terminated array of directory names.  It's
393  * legitimate to set *RETP to NULL to indicate there are no
394  * directories.  The function returns 0 on success or a negative value
395  * on a failure.
396  *
397  * If PRIVATE is set, the list in *RETP should contain only user's own
398  * directories (presumably under HOME if there's any such thing on the
399  * given OS).  Otherwise only system directories should be reported.
400  *
401  * The directories don't have to exist.  Directories passed in -F are
402  * handled separately by the caller and this callback shouldn't
403  * concern itself with it.  */
404 int os_get_config_dirs(int private, const char ***retp);
405
406 /* This is called to obtain list of legacy config files to import, if
407  * any.  A reference to initialized vector of char* is passed in.
408  *
409  * This returns 0 on success, in which case strings from *RETP (if
410  * any) are interpreted as files names.  These files belong to the
411  * caller and will eventually be freed.
412  *
413  * Returns a negative value for failure, in which case *RETP contents
414  * are not consulted in any way.  */
415 int os_get_ltrace_conf_filenames(struct vect *retp);
416
417 /* If arch.h defines ARCH_HAVE_FETCH_ARG, the following callbacks have
418  * to be implemented: arch_fetch_arg_init, arch_fetch_arg_clone,
419  * arch_fetch_arg_done, arch_fetch_arg_next and arch_fetch_retval.
420  * See fetch.h for details.  */
421
422 /* If arch.h defines both ARCH_HAVE_FETCH_ARG and
423  * ARCH_HAVE_FETCH_PACK, the following callbacks have to be
424  * implemented: arch_fetch_param_pack_start,
425  * arch_fetch_param_pack_end.  See fetch.h for details.  */
426
427 enum sw_singlestep_status {
428         SWS_FAIL,
429         SWS_OK,
430         SWS_HW,
431 };
432 struct sw_singlestep_data;
433
434 /* The following callback has to be implemented in backend if arch.h
435  * defines ARCH_HAVE_SW_SINGLESTEP.
436  *
437  * This is called before the OS backend requests hardware singlestep.
438  * arch_sw_singlestep should consider whether a singlestep needs to be
439  * done in software.  If not, it returns SWS_HW.  Otherwise it needs
440  * to add one or several breakpoints by calling ADD_CB.  When it is
441  * done, it continues the process as appropriate, and answers either
442  * SWS_OK, or SWS_FAIL, depending on how it went.
443  *
444  * PROC is the process that should perform the singlestep, BP the
445  * breakpoint that we are singlestepping over.  ADD_CB is a callback
446  * to request adding breakpoints that should trap the process after
447  * it's continued.  The arguments to ADD_CB are the address where the
448  * breakpoint should be added, and DATA.  ADD_CB returns 0 on success
449  * or a negative value on failure.  It is expected that
450  * arch_sw_singlestep returns SWS_FAIL if ADD_CB returns error.  */
451 enum sw_singlestep_status arch_sw_singlestep(struct process *proc,
452                                              struct breakpoint *bp,
453                                              int (*add_cb)(arch_addr_t addr,
454                                                    struct sw_singlestep_data *),
455                                              struct sw_singlestep_data *data);
456
457 #endif /* BACKEND_H */