Home | History | Annotate | Download | only in ltrace
      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, arch_addr_t addr,
    175 		  void *buf, size_t count);
    176 
    177 /* Find out an address of symbol SYM in process PROC, and return.
    178  * Returning NULL delays breakpoint insertion and enables heaps of
    179  * arch-specific black magic that we should clean up some day.
    180  *
    181  * XXX the same points as for get_instruction_pointer apply. */
    182 void *sym2addr(struct process *proc, struct library_symbol *sym);
    183 
    184 /* Obtain address of PLT entry corresponding to relocation RELA in
    185  * file LTE.  This is NDX-th PLT entry in the file.
    186  *
    187  * XXX should this return arch_addr_t?  */
    188 GElf_Addr arch_plt_sym_val(struct ltelf *lte, size_t ndx, GElf_Rela *rela);
    189 
    190 /* Called at some point after we have attached to PROC.  This callback
    191  * should insert an introspection breakpoint for handling dynamic
    192  * linker library loads.  */
    193 int linkmap_init(struct process *proc, arch_addr_t dyn_addr);
    194 
    195 /* This should produce and return the next event of one of the traced
    196  * processes.  The returned pointer will not be freed by the core and
    197  * should be either statically allocated, or the management should be
    198  * done some other way.  */
    199 struct Event *next_event(void);
    200 
    201 /* Called when process PROC was removed.  */
    202 void process_removed(struct process *proc);
    203 
    204 /* This should extract entry point address and interpreter (dynamic
    205  * linker) bias if possible.  Returns 0 if there were no errors, -1
    206  * otherwise.  Sets *ENTRYP and *INTERP_BIASP to non-zero values if
    207  * the corresponding value is known, or zero otherwise; this is not
    208  * done for pointers that are NULL.  */
    209 int process_get_entry(struct process *proc,
    210 		      arch_addr_t *entryp,
    211 		      arch_addr_t *interp_biasp);
    212 
    213 
    214 /* Optional callbacks
    216  *
    217  * Some callbacks are only available if backend (arch.h) has a certain
    218  * define.  If such a define is not present, default implementation
    219  * (most often doing nothing at all) us used instead.  This is used
    220  * for gradual extensions of ltrace, so that backends that are not
    221  * fully up to date, or that don't need certain functionality, keep
    222  * working, while other backends take advantage of the optional
    223  * features.  */
    224 
    225 /* The following callbacks have to be implemented in backend if arch.h
    226  * defines ARCH_HAVE_LTELF_DATA.  Those are used to init and destroy
    227  * LTE->arch.  arch_elf_init returns 0 on success or a negative value
    228  * on failure.  */
    229 int arch_elf_init(struct ltelf *lte, struct library *lib);
    230 void arch_elf_destroy(struct ltelf *lte);
    231 
    232 /* The following callbacks have to be implemented in OS backend if
    233  * os.h defines OS_HAVE_BREAKPOINT_DATA.  Those are used to init,
    234  * destroy, and clone SBP->os.  os_breakpoint_init and
    235  * os_breakpoint_clone return 0 on success or a negative value on
    236  * failure.  */
    237 int os_breakpoint_init(struct process *proc, struct breakpoint *sbp);
    238 void os_breakpoint_destroy(struct breakpoint *sbp);
    239 int os_breakpoint_clone(struct breakpoint *retp, struct breakpoint *sbp);
    240 
    241 /* The following callbacks have to be implemented in backend if arch.h
    242  * defines ARCH_HAVE_BREAKPOINT_DATA.  Those are used to init,
    243  * destroy, and clone SBP->arch.  arch_breakpoint_init and
    244  * arch_breakpoint_clone return 0 on success or a negative value on
    245  * failure.  */
    246 int arch_breakpoint_init(struct process *proc, struct breakpoint *sbp);
    247 void arch_breakpoint_destroy(struct breakpoint *sbp);
    248 int arch_breakpoint_clone(struct breakpoint *retp, struct breakpoint *sbp);
    249 
    250 /* The following callbacks have to be implemented in OS backend if
    251  * os.h defines OS_HAVE_LIBRARY_DATA.  Those are used to init, destroy
    252  * and clone LIB->os.  os_library_init and os_library_clone return 0
    253  * on success or a negative value on failure.  */
    254 int os_library_init(struct library *lib);
    255 void os_library_destroy(struct library *lib);
    256 int os_library_clone(struct library *retp, struct library *lib);
    257 
    258 /* The following callbacks have to be implemented in backend if arch.h
    259  * defines ARCH_HAVE_LIBRARY_DATA.  Those are used to init, destroy
    260  * and clone LIB->arch.  arch_library_init and arch_library_clone
    261  * return 0 on success or a negative value on failure.  */
    262 int arch_library_init(struct library *lib);
    263 void arch_library_destroy(struct library *lib);
    264 int arch_library_clone(struct library *retp, struct library *lib);
    265 
    266 /* The following callbacks have to be implemented in OS backend if
    267  * os.h defines OS_HAVE_LIBRARY_SYMBOL_DATA.  Those are used to init,
    268  * destroy and clone LIBSYM->os.  os_library_symbol_init and
    269  * os_library_symbol_clone return 0 on success or a negative value on
    270  * failure.  */
    271 int os_library_symbol_init(struct library_symbol *libsym);
    272 void os_library_symbol_destroy(struct library_symbol *libsym);
    273 int os_library_symbol_clone(struct library_symbol *retp,
    274 			    struct library_symbol *libsym);
    275 
    276 /* The following callbacks have to be implemented in backend if arch.h
    277  * defines ARCH_HAVE_LIBRARY_SYMBOL_DATA.  Those are used to init,
    278  * destroy and clone LIBSYM->arch.  arch_library_symbol_init and
    279  * arch_library_symbol_clone return 0 on success or a negative value
    280  * on failure.  */
    281 int arch_library_symbol_init(struct library_symbol *libsym);
    282 void arch_library_symbol_destroy(struct library_symbol *libsym);
    283 int arch_library_symbol_clone(struct library_symbol *retp,
    284 			      struct library_symbol *libsym);
    285 
    286 /* The following callbacks have to be implemented in OS backend if
    287  * os.h defines OS_HAVE_PROCESS_DATA.  The protocol is same as for,
    288  * respectively, arch_process_init, arch_process_destroy,
    289  * arch_process_clone and arch_process_exec.  */
    290 int os_process_init(struct process *proc);
    291 void os_process_destroy(struct process *proc);
    292 int os_process_clone(struct process *retp, struct process *proc);
    293 int os_process_exec(struct process *proc);
    294 
    295 /* The following callbacks have to be implemented in backend if arch.h
    296  * defines ARCH_HAVE_PROCESS_DATA.  Those are used to init, destroy
    297  * and clone PROC->arch.  arch_process_exec is called to update
    298  * PROC->arch in case that PROC underwent an exec.  See notes at
    299  * process_init, process_destroy, process_clone and process_exec in
    300  * proc.h.  */
    301 int arch_process_init(struct process *proc);
    302 void arch_process_destroy(struct process *proc);
    303 int arch_process_clone(struct process *retp, struct process *proc);
    304 int arch_process_exec(struct process *proc);
    305 
    306 /* The following callback has to be implemented in backend if arch.h
    307  * defines ARCH_HAVE_GET_SYM_INFO.
    308  *
    309  * This is called for every PLT relocation RELA in ELF file LTE (which
    310  * is named FILENAME), that ltrace is about to add.  The corresponding
    311  * PLT entry is for SYM_INDEX-th relocation in the file.  This call is
    312  * supposed to initialize SYM and RELA.  It returns 0 if there were no
    313  * errors and given symbol should be used, 1 if the symbol should not
    314  * be used, or a negative value if there were errors.  */
    315 int arch_get_sym_info(struct ltelf *lte, const char *filename, size_t sym_index,
    316 		      GElf_Rela *rela, GElf_Sym *sym);
    317 
    318 enum plt_status {
    319 	PLT_FAIL,
    320 	PLT_OK,
    321 	PLT_DEFAULT,
    322 };
    323 
    324 /* The following callback has to be implemented in OS backend if os.h
    325  * defines OS_HAVE_ADD_PLT_ENTRY.
    326  *
    327  * This is called for every PLT relocation R in ELF file LTE, that
    328  * ltrace is about to add to a library constructed in process PROC.
    329  * The corresponding PLT entry is for symbol called NAME, and it's
    330  * I-th relocation in the file.
    331  *
    332  * If this function returns PLT_DEFAULT, PLT address is obtained by
    333  * calling arch_plt_sym_val, and symbol is allocated.  If PLT_OK or
    334  * PLT_DEFAULT are returned, the chain of symbols passed back in RET
    335  * is added to library under construction.  */
    336 enum plt_status os_elf_add_plt_entry(struct process *proc, struct ltelf *lte,
    337 				     const char *name, GElf_Rela *rela,
    338 				     size_t i, struct library_symbol **ret);
    339 
    340 /* Like os_elf_add_plt_entry, but tied to ARCH_HAVE_ADD_PLT_ENTRY in
    341  * arch.h.  The arch callback is called first.  If it returns
    342  * PLT_DEFAULT, the os callback is called next.  */
    343 enum plt_status arch_elf_add_plt_entry(struct process *proc, struct ltelf *lte,
    344 				       const char *name, GElf_Rela *rela,
    345 				       size_t i, struct library_symbol **ret);
    346 
    347 /* The following callback has to be implemented in OS backend if os.h
    348  * defines OS_HAVE_ADD_FUNC_ENTRY.
    349  *
    350  * This is called for every symbol in ltrace is about to add to the
    351  * library constructed for LTE in process PROC.
    352  *
    353  * If this function returns PLT_DEFAULT, then if there is a
    354  * pre-existing symbol, its name may be updated if the newly-found
    355  * name is shorter.  Otherwise a new symbol is created.
    356  *
    357  * If PLT_OK or PLT_DEFAULT are returned, the chain of symbols passed
    358  * back in RET is added to library under construction.  */
    359 enum plt_status os_elf_add_func_entry(struct process *proc, struct ltelf *lte,
    360 				      const GElf_Sym *sym,
    361 				      arch_addr_t addr, const char *name,
    362 				      struct library_symbol **ret);
    363 
    364 /* Like os_elf_add_func_entry, but tied to ARCH_HAVE_ADD_FUNC_ENTRY in
    365  * arch.h.  The arch callback is called first.  If it returns
    366  * PLT_DEFAULT, the os callback is called next.  */
    367 enum plt_status arch_elf_add_func_entry(struct process *proc, struct ltelf *lte,
    368 					const GElf_Sym *sym,
    369 					arch_addr_t addr, const char *name,
    370 					struct library_symbol **ret);
    371 
    372 /* This callback needs to be implemented if arch.h defines
    373  * ARCH_HAVE_DYNLINK_DONE.  It is called after the dynamic linker is
    374  * done with the process start-up.  */
    375 void arch_dynlink_done(struct process *proc);
    376 
    377 /* This callback needs to be implemented if arch.h defines
    378  * ARCH_HAVE_SYMBOL_RET.  It is called after a traced call returns.  */
    379 void arch_symbol_ret(struct process *proc, struct library_symbol *libsym);
    380 
    381 
    382 /* This callback needs to be implemented if arch.h defines
    383  * ARCH_HAVE_FIND_DL_DEBUG.
    384  * It is called by generic code to find the address of the dynamic
    385  * linkers debug structure.
    386  * DYN_ADDR holds the address of the dynamic section.
    387  * If the debug area is found, return 0 and fill in the address in *RET.
    388  * If the debug area is not found, return a negative value.  */
    389 int arch_find_dl_debug(struct process *proc, arch_addr_t dyn_addr,
    390 		       arch_addr_t *ret);
    391 
    392 /* This is called to obtain a list of directories to search when
    393  * loading config files.  The callback sets *RETP to a pointer to the
    394  * first element of a NULL-terminated array of directory names.  It's
    395  * legitimate to set *RETP to NULL to indicate there are no
    396  * directories.  The function returns 0 on success or a negative value
    397  * on a failure.
    398  *
    399  * If PRIVATE is set, the list in *RETP should contain only user's own
    400  * directories (presumably under HOME if there's any such thing on the
    401  * given OS).  Otherwise only system directories should be reported.
    402  *
    403  * The directories don't have to exist.  Directories passed in -F are
    404  * handled separately by the caller and this callback shouldn't
    405  * concern itself with it.  */
    406 int os_get_config_dirs(int private, const char ***retp);
    407 
    408 /* This is called to obtain list of legacy config files to import, if
    409  * any.  A reference to initialized vector of char* is passed in.
    410  *
    411  * This returns 0 on success, in which case strings from *RETP (if
    412  * any) are interpreted as files names.  These files belong to the
    413  * caller and will eventually be freed.
    414  *
    415  * Returns a negative value for failure, in which case *RETP contents
    416  * are not consulted in any way.  */
    417 int os_get_ltrace_conf_filenames(struct vect *retp);
    418 
    419 /* If arch.h defines ARCH_HAVE_FETCH_ARG, the following callbacks have
    420  * to be implemented: arch_fetch_arg_init, arch_fetch_arg_clone,
    421  * arch_fetch_arg_done, arch_fetch_arg_next and arch_fetch_retval.
    422  * See fetch.h for details.  */
    423 
    424 /* If arch.h defines both ARCH_HAVE_FETCH_ARG and
    425  * ARCH_HAVE_FETCH_PACK, the following callbacks have to be
    426  * implemented: arch_fetch_param_pack_start,
    427  * arch_fetch_param_pack_end.  See fetch.h for details.  */
    428 
    429 enum sw_singlestep_status {
    430 	SWS_FAIL,
    431 	SWS_OK,
    432 	SWS_HW,
    433 };
    434 struct sw_singlestep_data;
    435 
    436 /* The following callback has to be implemented in backend if arch.h
    437  * defines ARCH_HAVE_SW_SINGLESTEP.
    438  *
    439  * This is called before the OS backend requests hardware singlestep.
    440  * arch_sw_singlestep should consider whether a singlestep needs to be
    441  * done in software.  If not, it returns SWS_HW.  Otherwise it needs
    442  * to add one or several breakpoints by calling ADD_CB.  When it is
    443  * done, it continues the process as appropriate, and answers either
    444  * SWS_OK, or SWS_FAIL, depending on how it went.
    445  *
    446  * PROC is the process that should perform the singlestep, BP the
    447  * breakpoint that we are singlestepping over.  ADD_CB is a callback
    448  * to request adding breakpoints that should trap the process after
    449  * it's continued.  The arguments to ADD_CB are the address where the
    450  * breakpoint should be added, and DATA.  ADD_CB returns 0 on success
    451  * or a negative value on failure.  It is expected that
    452  * arch_sw_singlestep returns SWS_FAIL if ADD_CB returns error.  */
    453 enum sw_singlestep_status arch_sw_singlestep(struct process *proc,
    454 					     struct breakpoint *bp,
    455 					     int (*add_cb)(arch_addr_t addr,
    456 						   struct sw_singlestep_data *),
    457 					     struct sw_singlestep_data *data);
    458 
    459 #endif /* BACKEND_H */
    460