Imported Upstream version 0.7.2upstream/0.7.2

1 files changed, 343 insertions, 0 deletions

diff --git a/backend.h b/backend.h
new file mode 100644
index 0000000..89c05c3
--- /dev/null
+++ b/backend.h
@@ -0,0 +1,343 @@
+/*
+ * This file is part of ltrace.
+ * Copyright (C) 2012 Petr Machata, Red Hat Inc.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA
+ */
+
+#ifndef BACKEND_H
+#define BACKEND_H
+
+#include "forward.h"
+#include "sysdep.h"
+
+#include <gelf.h>
+
+enum process_status {
+	ps_invalid,	/* Failure.  */
+	ps_stop,	/* Job-control stop.  */
+	ps_tracing_stop,
+	ps_sleeping,
+	ps_zombie,
+	ps_other,	/* Necessary other states can be added as needed.  */
+};
+
+/*
+ * This file contains documentation of back end interface.  Some of
+ * these may be implemented on an OS level (i.e. they are the same
+ * e.g. on all Linux architectures), some may differ per architecture
+ * on the same OS (e.g. a way to insert a breakpoint into the process
+ * image is a likely candidate).
+ */
+
+/* Convert a PID to a path to the corresponding binary.  */
+char *pid2name(pid_t pid);
+
+/* Given a PID, find a leader of thread group.  */
+pid_t process_leader(pid_t pid);
+
+/* Given a PID of leader thread, fill in PIDs of all the tasks.  The
+ * function will initialize the pointer *RET_TASKS to a
+ * newly-allocated array, and will store number of elements in that
+ * array to *RET_N.  You have to free that buffer when you don't need
+ * it anymore.  */
+int process_tasks(pid_t pid, pid_t **ret_tasks, size_t *ret_n);
+
+/* Answer whether the process PID is stopped.  Returns 0 when not
+ * stopped, 1 when stopped, or -1 when there was an error.  */
+int process_stopped(pid_t pid);
+
+/* Answer a status of the task PID.  See enum process_status.  */
+enum process_status process_status(pid_t pid);
+
+/* Wait for PID to be ready for tracing.  */
+int wait_for_proc(pid_t pid);
+
+/* Send a signal SIG to the task PID.  */
+int task_kill(pid_t pid, int sig);
+
+/* Called after PID is attached, but before it is continued.  */
+void trace_set_options(struct Process *proc);
+
+/* Called after ltrace forks.  Should attach the newly created child,
+ * in whose context this function is called.  */
+void trace_me(void);
+
+/* Called when ltrace needs to attach to PID, such as when it attaches
+ * to a running process, whose PID is given on the command line.  */
+int trace_pid(pid_t pid);
+
+/* Stop tracing PID.  */
+void untrace_pid(pid_t pid);
+
+/* The back end may need to store arbitrary data to a process.  This
+ * is a place where it can initialize PROC->arch_dep.  XXX this should
+ * be dropped in favor of arhc_process_init on pmachata/libs.  */
+void get_arch_dep(struct Process *proc);
+
+/* Return current instruction pointer of PROC.
+ *
+ * XXX note that the IP must fit into an arch pointer.  This prevents
+ * us to use 32-bit ltrace to trace 64-bit process, even on arches
+ * that would otherwise support this.  Above we have a definition of
+ * arch_addr_t.  This should be converted to an integral type and
+ * used for target addresses throughout.  */
+void *get_instruction_pointer(struct Process *proc);
+
+/* Set instruction pointer of PROC to ADDR.  XXX see above.  */
+void set_instruction_pointer(struct Process *proc, void *addr);
+
+/* Return current stack pointer of PROC.  XXX see above.  */
+void *get_stack_pointer(struct Process *proc);
+
+/* Find and return caller address, i.e. the address where the current
+ * function returns.  */
+void *get_return_addr(struct Process *proc, void *stack_pointer);
+
+/* Adjust PROC so that when the current function returns, it returns
+ * to ADDR.  */
+void set_return_addr(struct Process *proc, void *addr);
+
+/* Enable breakpoint SBP in process PROC.  */
+void enable_breakpoint(struct Process *proc, struct breakpoint *sbp);
+
+/* Disable breakpoint SBP in process PROC.  */
+void disable_breakpoint(struct Process *proc, struct breakpoint *sbp);
+
+/* Determine whether the event that we have just seen (and that is
+ * recorded in STATUS) was a syscall.  If it was, return 1.  If it was
+ * a return from syscall, return 2.  In both cases, set *SYSNUM to the
+ * number of said syscall.  If it wasn't a syscall, return 0.  If
+ * there was an error, return -1.  */
+int syscall_p(struct Process *proc, int status, int *sysnum);
+
+/* Continue execution of the process with given PID.  */
+void continue_process(pid_t pid);
+
+/* Called after we received a signal SIGNUM.  Should do whatever
+ * book-keeping is necessary and continue the process if
+ * necessary.  */
+void continue_after_signal(pid_t pid, int signum);
+
+/* Called after we received a system call SYSNUM.  RET_P is 0 if this
+ * is system call, otherwise it's return from a system call.  The
+ * callback should do whatever book-keeping is necessary and continue
+ * the process if necessary.  */
+void continue_after_syscall(struct Process *proc, int sysnum, int ret_p);
+
+/* Called after we hit a breakpoint SBP.  Should do whatever
+ * book-keeping is necessary and then continue the process.  */
+void continue_after_breakpoint(struct Process *proc, struct breakpoint *sbp);
+
+/* Called after we received a vfork.  Should do whatever book-keeping
+ * is necessary and continue the process if necessary.  N.B. right
+ * now, with Linux/GNU the only back end, this is not necessary.  I
+ * imagine other systems may be different.  */
+void continue_after_vfork(struct Process *proc);
+
+/* Called when trace_me or primary trace_pid fail.  This may plug in
+ * any platform-specific knowledge of why it could be so.  */
+void trace_fail_warning(pid_t pid);
+
+/* A pair of functions called to initiate a detachment request when
+ * ltrace is about to exit.  Their job is to undo any effects that
+ * tracing had and eventually detach process, perhaps by way of
+ * installing a process handler.
+ *
+ * OS_LTRACE_EXITING_SIGHANDLER is called from a signal handler
+ * context right after the signal was captured.  It returns 1 if the
+ * request was handled or 0 if it wasn't.
+ *
+ * If the call to OS_LTRACE_EXITING_SIGHANDLER didn't handle the
+ * request, OS_LTRACE_EXITING is called when the next event is
+ * generated.  Therefore it's called in "safe" context, without
+ * re-entrancy concerns, but it's only called after an even is
+ * generated.  */
+int os_ltrace_exiting_sighandler(void);
+void os_ltrace_exiting(void);
+
+/* Should copy COUNT bytes from address ADDR of process PROC to local
+ * buffer BUF.  */
+size_t umovebytes (struct Process *proc, void *addr, void *buf, size_t count);
+
+/* Find out an address of symbol SYM in process PROC, and return.
+ * Returning NULL delays breakpoint insertion and enables heaps of
+ * arch-specific black magic that we should clean up some day.
+ *
+ * XXX the same points as for get_instruction_pointer apply. */
+void *sym2addr(struct Process *proc, struct library_symbol *sym);
+
+/* Obtain address of PLT entry corresponding to relocation RELA in
+ * file LTE.  This is NDX-th PLT entry in the file.
+ *
+ * XXX should this return arch_addr_t?  */
+GElf_Addr arch_plt_sym_val(struct ltelf *lte, size_t ndx, GElf_Rela *rela);
+
+/* Called at some point after we have attached to PROC.  This callback
+ * should insert an introspection breakpoint for handling dynamic
+ * linker library loads.  */
+int linkmap_init(struct Process *proc, arch_addr_t dyn_addr);
+
+/* This should produce and return the next event of one of the traced
+ * processes.  The returned pointer will not be freed by the core and
+ * should be either statically allocated, or the management should be
+ * done some other way.  */
+struct Event *next_event(void);
+
+/* Called when process PROC was removed.  */
+void process_removed(struct Process *proc);
+
+/* This should extract entry point address and interpreter (dynamic
+ * linker) bias if possible.  Returns 0 if there were no errors, -1
+ * otherwise.  Sets *ENTRYP and *INTERP_BIASP to non-zero values if
+ * the corresponding value is known, or zero otherwise; this is not
+ * done for pointers that are NULL.  */
+int process_get_entry(struct Process *proc,
+		      arch_addr_t *entryp,
+		      arch_addr_t *interp_biasp);
+
+
+/* Optional callbacks
+ *
+ * Some callbacks are only available if backend (arch.h) has a certain
+ * define.  If such a define is not present, default implementation
+ * (most often doing nothing at all) us used instead.  This is used
+ * for gradual extensions of ltrace, so that backends that are not
+ * fully up to date, or that don't need certain functionality, keep
+ * working, while other backends take advantage of the optional
+ * features.  */
+
+/* The following callbacks have to be implemented in backend if arch.h
+ * defines ARCH_HAVE_LTELF_DATA.  Those are used to init and destroy
+ * LTE->arch.  arch_elf_init returns 0 on success or a negative value
+ * on failure.  */
+int arch_elf_init(struct ltelf *lte, struct library *lib);
+void arch_elf_destroy(struct ltelf *lte);
+
+/* The following callbacks have to be implemented in backend if arch.h
+ * defines ARCH_HAVE_BREAKPOINT_DATA.  Those are used to init,
+ * destroy, and clone SBP->arch.  arch_breakpoint_init and
+ * arch_breakpoint_clone return 0 on success or a negative value on
+ * failure.  */
+int arch_breakpoint_init(struct Process *proc, struct breakpoint *sbp);
+void arch_breakpoint_destroy(struct breakpoint *sbp);
+int arch_breakpoint_clone(struct breakpoint *retp, struct breakpoint *sbp);
+
+/* The following callbacks have to be implemented in backend if arch.h
+ * defines ARCH_HAVE_LIBRARY_DATA.  Those are used to init, destroy
+ * and clone LIB->arch.  */
+void arch_library_init(struct library *lib);
+void arch_library_destroy(struct library *lib);
+void arch_library_clone(struct library *retp, struct library *lib);
+
+/* The following callbacks have to be implemented in backend if arch.h
+ * defines ARCH_HAVE_LIBRARY_SYMBOL_DATA.  Those are used to init,
+ * destroy and clone LIBSYM->arch.  arch_library_symbol_init and
+ * arch_library_symbol_clone return 0 on success or a negative value
+ * on failure.  */
+int arch_library_symbol_init(struct library_symbol *libsym);
+void arch_library_symbol_destroy(struct library_symbol *libsym);
+int arch_library_symbol_clone(struct library_symbol *retp,
+			      struct library_symbol *libsym);
+
+/* The following callbacks have to be implemented in backend if arch.h
+ * defines ARCH_HAVE_PROCESS_DATA.  Those are used to init, destroy
+ * and clone PROC->arch.  arch_process_exec is called to update
+ * PROC->arch in case that PROC underwent an exec.  See notes at
+ * process_init, process_destroy, process_clone and process_exec in
+ * proc.h.  */
+int arch_process_init(struct Process *proc);
+void arch_process_destroy(struct Process *proc);
+int arch_process_clone(struct Process *retp, struct Process *proc);
+int arch_process_exec(struct Process *proc);
+
+/* The following callbacks have to be implemented in OS backend if
+ * os.h defines OS_HAVE_PROCESS_DATA.  The protocol is same as for,
+ * respectively, arch_process_init, arch_process_destroy,
+ * arch_process_clone and arch_process_exec.  */
+int os_process_init(struct Process *proc);
+void os_process_destroy(struct Process *proc);
+int os_process_clone(struct Process *retp, struct Process *proc);
+int os_process_exec(struct Process *proc);
+
+/* The following callback has to be implemented in backend if arch.h
+ * defines ARCH_HAVE_GET_SYM_INFO.
+ *
+ * This is called for every PLT relocation R in ELF file LTE, that
+ * ltrace is about to add to it's internal representation of the
+ * program under trace.
+ * The corresponding PLT entry is for SYM_INDEX-th relocation in the file.
+ *
+ * The callback is responsible for initializing RELA and SYM.
+ *
+ * Return 0 if OK.
+ * Return a negative value if this symbol (SYM_INDEX) should be ignored.  */
+int arch_get_sym_info(struct ltelf *lte, const char *filename,
+		      size_t sym_index, GElf_Rela *rela, GElf_Sym *sym);
+
+enum plt_status {
+	plt_fail,
+	plt_ok,
+	plt_default,
+};
+
+/* The following callback has to be implemented in backend if arch.h
+ * defines ARCH_HAVE_ADD_PLT_ENTRY.
+ *
+ * This is called for every PLT relocation R in ELF file LTE, that
+ * ltrace is about to add to a library constructed in process PROC.
+ * The corresponding PLT entry is for symbol called NAME, and it's
+ * I-th relocation in the file.
+ *
+ * If this function returns plt_default, PLT address is obtained by
+ * calling arch_plt_sym_val, and symbol is allocated.  If plt_ok or
+ * plt_default are returned, the chain of symbols passed back in RET
+ * is added to library under construction.  */
+enum plt_status arch_elf_add_plt_entry(struct Process *proc, struct ltelf *lte,
+				       const char *name, GElf_Rela *rela,
+				       size_t i, struct library_symbol **ret);
+
+/* This callback needs to be implemented if arch.h defines
+ * ARCH_HAVE_DYNLINK_DONE.  It is called after the dynamic linker is
+ * done with the process startup.  */
+void arch_dynlink_done(struct Process *proc);
+
+/* This callback needs to be implemented if arch.h defines
+ * ARCH_HAVE_SYMBOL_RET.  It is called after a traced call returns.  */
+void arch_symbol_ret(struct Process *proc, struct library_symbol *libsym);
+
+
+/* This callback needs to be implemented if arch.h defines
+ * ARCH_HAVE_FIND_DL_DEBUG.
+ * It is called by generic code to find the address of the dynamic
+ * linkers debug structure.
+ * DYN_ADDR holds the address of the dynamic section.
+ * If the debug area is found, return 0 and fill in the address in *RET.
+ * If the debug area is not found, return a negative value.  */
+int arch_find_dl_debug(struct Process *proc, arch_addr_t dyn_addr,
+		       arch_addr_t *ret);
+
+/* If arch.h defines ARCH_HAVE_FETCH_ARG, the following callbacks have
+ * to be implemented: arch_fetch_arg_init, arch_fetch_arg_clone,
+ * arch_fetch_arg_done, arch_fetch_arg_next and arch_fetch_retval.
+ * See fetch.h for details.  */
+
+/* If arch.h defines both ARCH_HAVE_FETCH_ARG and
+ * ARCH_HAVE_FETCH_PACK, the following callbacks have to be
+ * implemented: arch_fetch_param_pack_start,
+ * arch_fetch_param_pack_end.  See fetch.h for details.  */
+
+#endif /* BACKEND_H */