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
