backend.h

   1 /*
   2  * This file is part of ltrace.
   3  * Copyright (C) 2012 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 /* Adjust PROC so that when the current function returns, it returns
 111  * to ADDR.  */
 112 void set_return_addr(struct Process *proc, void *addr);
 113
 114 /* Enable breakpoint SBP in process PROC.  */
 115 void enable_breakpoint(struct Process *proc, struct breakpoint *sbp);
 116
 117 /* Disable breakpoint SBP in process PROC.  */
 118 void disable_breakpoint(struct Process *proc, struct breakpoint *sbp);
 119
 120 /* Determine whether the event that we have just seen (and that is
 121  * recorded in STATUS) was a syscall.  If it was, return 1.  If it was
 122  * a return from syscall, return 2.  In both cases, set *SYSNUM to the
 123  * number of said syscall.  If it wasn't a syscall, return 0.  If
 124  * there was an error, return -1.  */
 125 int syscall_p(struct Process *proc, int status, int *sysnum);
 126
 127 /* Continue execution of the process with given PID.  */
 128 void continue_process(pid_t pid);
 129
 130 /* Called after we received a signal SIGNUM.  Should do whatever
 131  * book-keeping is necessary and continue the process if
 132  * necessary.  */
 133 void continue_after_signal(pid_t pid, int signum);
 134
 135 /* Called after we received a system call SYSNUM.  RET_P is 0 if this
 136  * is system call, otherwise it's return from a system call.  The
 137  * callback should do whatever book-keeping is necessary and continue
 138  * the process if necessary.  */
 139 void continue_after_syscall(struct Process *proc, int sysnum, int ret_p);
 140
 141 /* Called after we hit a breakpoint SBP.  Should do whatever
 142  * book-keeping is necessary and then continue the process.  */
 143 void continue_after_breakpoint(struct Process *proc, struct breakpoint *sbp);
 144
 145 /* Called after we received a vfork.  Should do whatever book-keeping
 146  * is necessary and continue the process if necessary.  N.B. right
 147  * now, with Linux/GNU the only back end, this is not necessary.  I
 148  * imagine other systems may be different.  */
 149 void continue_after_vfork(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 backend if arch.h
 231  * defines ARCH_HAVE_BREAKPOINT_DATA.  Those are used to init,
 232  * destroy, and clone SBP->arch.  arch_breakpoint_init and
 233  * arch_breakpoint_clone return 0 on success or a negative value on
 234  * failure.  */
 235 int arch_breakpoint_init(struct Process *proc, struct breakpoint *sbp);
 236 void arch_breakpoint_destroy(struct breakpoint *sbp);
 237 int arch_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_LIBRARY_DATA.  Those are used to init, destroy
 241  * and clone LIB->arch.  */
 242 void arch_library_init(struct library *lib);
 243 void arch_library_destroy(struct library *lib);
 244 void arch_library_clone(struct library *retp, struct library *lib);
 245
 246 /* The following callbacks have to be implemented in backend if arch.h
 247  * defines ARCH_HAVE_LIBRARY_SYMBOL_DATA.  Those are used to init,
 248  * destroy and clone LIBSYM->arch.  arch_library_symbol_init and
 249  * arch_library_symbol_clone return 0 on success or a negative value
 250  * on failure.  */
 251 int arch_library_symbol_init(struct library_symbol *libsym);
 252 void arch_library_symbol_destroy(struct library_symbol *libsym);
 253 int arch_library_symbol_clone(struct library_symbol *retp,
 254                               struct library_symbol *libsym);
 255
 256 /* The following callbacks have to be implemented in backend if arch.h
 257  * defines ARCH_HAVE_PROCESS_DATA.  Those are used to init, destroy
 258  * and clone PROC->arch.  arch_process_exec is called to update
 259  * PROC->arch in case that PROC underwent an exec.  See notes at
 260  * process_init, process_destroy, process_clone and process_exec in
 261  * proc.h.  */
 262 int arch_process_init(struct Process *proc);
 263 void arch_process_destroy(struct Process *proc);
 264 int arch_process_clone(struct Process *retp, struct Process *proc);
 265 int arch_process_exec(struct Process *proc);
 266
 267 /* The following callbacks have to be implemented in OS backend if
 268  * os.h defines OS_HAVE_PROCESS_DATA.  The protocol is same as for,
 269  * respectively, arch_process_init, arch_process_destroy,
 270  * arch_process_clone and arch_process_exec.  */
 271 int os_process_init(struct Process *proc);
 272 void os_process_destroy(struct Process *proc);
 273 int os_process_clone(struct Process *retp, struct Process *proc);
 274 int os_process_exec(struct Process *proc);
 275
 276 /* The following callback has to be implemented in backend if arch.h
 277  * defines ARCH_HAVE_GET_SYM_INFO.
 278  *
 279  * This is called for every PLT relocation R in ELF file LTE, that
 280  * ltrace is about to add to it's internal representation of the
 281  * program under trace.
 282  * The corresponding PLT entry is for SYM_INDEX-th relocation in the file.
 283  *
 284  * The callback is responsible for initializing RELA and SYM.
 285  *
 286  * Return 0 if OK.
 287  * Return a negative value if this symbol (SYM_INDEX) should be ignored.  */
 288 int arch_get_sym_info(struct ltelf *lte, const char *filename,
 289                       size_t sym_index, GElf_Rela *rela, GElf_Sym *sym);
 290
 291 enum plt_status {
 292         plt_fail,
 293         plt_ok,
 294         plt_default,
 295 };
 296
 297 /* The following callback has to be implemented in backend if arch.h
 298  * defines ARCH_HAVE_ADD_PLT_ENTRY.
 299  *
 300  * This is called for every PLT relocation R in ELF file LTE, that
 301  * ltrace is about to add to a library constructed in process PROC.
 302  * The corresponding PLT entry is for symbol called NAME, and it's
 303  * I-th relocation in the file.
 304  *
 305  * If this function returns plt_default, PLT address is obtained by
 306  * calling arch_plt_sym_val, and symbol is allocated.  If plt_ok or
 307  * plt_default are returned, the chain of symbols passed back in RET
 308  * is added to library under construction.  */
 309 enum plt_status arch_elf_add_plt_entry(struct Process *proc, struct ltelf *lte,
 310                                        const char *name, GElf_Rela *rela,
 311                                        size_t i, struct library_symbol **ret);
 312
 313 /* This callback needs to be implemented if arch.h defines
 314  * ARCH_HAVE_DYNLINK_DONE.  It is called after the dynamic linker is
 315  * done with the process startup.  */
 316 void arch_dynlink_done(struct Process *proc);
 317
 318 /* This callback needs to be implemented if arch.h defines
 319  * ARCH_HAVE_SYMBOL_RET.  It is called after a traced call returns.  */
 320 void arch_symbol_ret(struct Process *proc, struct library_symbol *libsym);
 321
 322
 323 /* This callback needs to be implemented if arch.h defines
 324  * ARCH_HAVE_FIND_DL_DEBUG.
 325  * It is called by generic code to find the address of the dynamic
 326  * linkers debug structure.
 327  * DYN_ADDR holds the address of the dynamic section.
 328  * If the debug area is found, return 0 and fill in the address in *RET.
 329  * If the debug area is not found, return a negative value.  */
 330 int arch_find_dl_debug(struct Process *proc, arch_addr_t dyn_addr,
 331                        arch_addr_t *ret);
 332
 333 /* If arch.h defines ARCH_HAVE_FETCH_ARG, the following callbacks have
 334  * to be implemented: arch_fetch_arg_init, arch_fetch_arg_clone,
 335  * arch_fetch_arg_done, arch_fetch_arg_next and arch_fetch_retval.
 336  * See fetch.h for details.  */
 337
 338 /* If arch.h defines both ARCH_HAVE_FETCH_ARG and
 339  * ARCH_HAVE_FETCH_PACK, the following callbacks have to be
 340  * implemented: arch_fetch_param_pack_start,
 341  * arch_fetch_param_pack_end.  See fetch.h for details.  */
 342
 343 #endif /* BACKEND_H */