backend.h revision bac2da505ee174b7fb984b975c5938f88f0dbab2 
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
29enum 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.  */
47char *pid2name(pid_t pid);
48
49/* Given a PID, find a leader of thread group.  */
50pid_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.  */
57int 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.  */
61int process_stopped(pid_t pid);
62
63/* Answer a status of the task PID.  See enum process_status.  */
64enum process_status process_status(pid_t pid);
65
66/* Wait for PID to be ready for tracing.  */
67int wait_for_proc(pid_t pid);
68
69/* Send a signal SIG to the task PID.  */
70int task_kill(pid_t pid, int sig);
71
72/* Called after PID is attached, but before it is continued.  */
73void 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.  */
77void 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.  */
81int trace_pid(pid_t pid);
82
83/* Stop tracing PID.  */
84void 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.  */
89void 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.  */
98void *get_instruction_pointer(struct Process *proc);
99
100/* Set instruction pointer of PROC to ADDR.  XXX see above.  */
101void set_instruction_pointer(struct Process *proc, void *addr);
102
103/* Return current stack pointer of PROC.  XXX see above.  */
104void *get_stack_pointer(struct Process *proc);
105
106/* Find and return caller address, i.e. the address where the current
107 * function returns.  */
108void *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.  */
112void set_return_addr(struct Process *proc, void *addr);
113
114/* Enable breakpoint SBP in process PROC.  */
115void enable_breakpoint(struct Process *proc, struct breakpoint *sbp);
116
117/* Disable breakpoint SBP in process PROC.  */
118void 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.  */
125int syscall_p(struct Process *proc, int status, int *sysnum);
126
127/* Continue execution of the process with given PID.  */
128void 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.  */
133void 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.  */
139void 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.  */
143void 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.  */
149void 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.  */
153void 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.  */
169int os_ltrace_exiting_sighandler(void);
170void os_ltrace_exiting(void);
171
172/* Should copy COUNT bytes from address ADDR of process PROC to local
173 * buffer BUF.  */
174size_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. */
181void *sym2addr(struct Process *proc, struct library_symbol *sym);
182
183/* Called at some point after we have attached to PROC.  This callback
184 * should insert an introspection breakpoint for handling dynamic
185 * linker library loads.  */
186int linkmap_init(struct Process *proc, arch_addr_t dyn_addr);
187
188/* Called for breakpoints defined over an artificial symbol "".  This
189 * can be used (like it is on Linux/GNU) to add more breakpoints
190 * because a dlopen'ed library was mapped in.
191 *
192 * XXX we should somehow clean up this interface.  For starters,
193 * breakpoints should have their own handler callbacks, so that we can
194 * generalize this to e.g. systemtap SDT probes.  linkmap_init could
195 * perhaps be rolled into some other process init callback.  */
196void arch_check_dbg(struct Process *proc);
197
198/* This should produce and return the next event of one of the traced
199 * processes.  The returned pointer will not be freed by the core and
200 * should be either statically allocated, or the management should be
201 * done some other way.  */
202struct Event *next_event(void);
203
204/* Called when process PROC was removed.  */
205void process_removed(struct Process *proc);
206
207int arch_elf_init(struct ltelf *lte, struct library *lib);
208void arch_elf_destroy(struct ltelf *lte);
209
210enum plt_status {
211	plt_fail,
212	plt_ok,
213	plt_default,
214};
215
216enum plt_status arch_elf_add_plt_entry(struct Process *p, struct ltelf *l,
217				       const char *n, GElf_Rela *r, size_t i,
218				       struct library_symbol **ret);
219
220int arch_breakpoint_init(struct Process *proc, struct breakpoint *sbp);
221void arch_breakpoint_destroy(struct breakpoint *sbp);
222int arch_breakpoint_clone(struct breakpoint *retp, struct breakpoint *sbp);
223
224void arch_library_init(struct library *lib);
225void arch_library_destroy(struct library *lib);
226void arch_library_clone(struct library *retp, struct library *lib);
227
228int arch_library_symbol_init(struct library_symbol *libsym);
229void arch_library_symbol_destroy(struct library_symbol *libsym);
230int arch_library_symbol_clone(struct library_symbol *retp,
231			      struct library_symbol *libsym);
232
233int arch_process_init(struct Process *proc);
234void arch_process_destroy(struct Process *proc);
235int arch_process_clone(struct Process *retp, struct Process *proc);
236int arch_process_exec(struct Process *proc);
237
238/* This should extract entry point address and interpreter (dynamic
239 * linker) bias if possible.  Returns 0 if there were no errors, -1
240 * otherwise.  Sets *ENTRYP and *INTERP_BIASP to non-zero values if
241 * the corresponding value is known.  Unknown values are set to 0.  */
242int process_get_entry(struct Process *proc,
243		      arch_addr_t *entryp,
244		      arch_addr_t *interp_biasp);
245
246/* This is called after the dynamic linker is done with the
247 * process startup.  */
248void arch_dynlink_done(struct Process *proc);
249
250#endif /* BACKEND_H */
251