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 */