ptrace.h revision f0c5872637a63e28e3cd314cfc915c07f76df9c6 
1501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown/*
2501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * Copyright (C) 2011 The Android Open Source Project
3501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown *
4501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * Licensed under the Apache License, Version 2.0 (the "License");
5501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * you may not use this file except in compliance with the License.
6501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * You may obtain a copy of the License at
7501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown *
8501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown *      http://www.apache.org/licenses/LICENSE-2.0
9501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown *
10501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * Unless required by applicable law or agreed to in writing, software
11501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * distributed under the License is distributed on an "AS IS" BASIS,
12501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * See the License for the specific language governing permissions and
14501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * limitations under the License.
15501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown */
16501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
17501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown/* Useful ptrace() utility functions. */
18501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
19501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#ifndef _CORKSCREW_PTRACE_H
20501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#define _CORKSCREW_PTRACE_H
21501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
22501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#include <corkscrew/map_info.h>
23501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#include <corkscrew/symbol_table.h>
24501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
25501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#include <sys/types.h>
26501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#include <stdbool.h>
27501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
28501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#ifdef __cplusplus
29501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brownextern "C" {
30501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#endif
31501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
32501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown/* Stores information about a process that is used for several different
33501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * ptrace() based operations. */
34501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Browntypedef struct {
35501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    map_info_t* map_info_list;
36501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown} ptrace_context_t;
37501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
38f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown/* Describes how to access memory from a process. */
39f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Browntypedef struct {
40f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown    pid_t tid;
41f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown    const map_info_t* map_info_list;
42f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown} memory_t;
43f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown
44501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#if __i386__
45501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown/* ptrace() register context. */
46501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Browntypedef struct pt_regs_x86 {
47501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t ebx;
48501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t ecx;
49501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t edx;
50501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t esi;
51501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t edi;
52501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t ebp;
53501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t eax;
54501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t xds;
55501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t xes;
56501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t xfs;
57501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t xgs;
58501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t orig_eax;
59501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t eip;
60501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t xcs;
61501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t eflags;
62501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t esp;
63501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown    uint32_t xss;
64501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown} pt_regs_x86_t;
65501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#endif
66501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
67501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown/*
68f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown * Initializes a memory structure for accessing memory from this process.
69f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown */
70f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brownvoid init_memory(memory_t* memory, const map_info_t* map_info_list);
71f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown
72f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown/*
73f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown * Initializes a memory structure for accessing memory from another process
74f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown * using ptrace().
75f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown */
76f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brownvoid init_memory_ptrace(memory_t* memory, pid_t tid);
77f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown
78f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown/*
79501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * Reads a word of memory safely.
80f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown * If the memory is local, ensures that the address is readable before dereferencing it.
81f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown * Returns false and a value of 0xffffffff if the word could not be read.
82f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown */
83f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brownbool try_get_word(const memory_t* memory, uintptr_t ptr, uint32_t* out_value);
84f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown
85f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown/*
86f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown * Reads a word of memory safely using ptrace().
87f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brown * Returns false and a value of 0xffffffff if the word could not be read.
88501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown */
89f0c5872637a63e28e3cd314cfc915c07f76df9c6Jeff Brownbool try_get_word_ptrace(pid_t tid, uintptr_t ptr, uint32_t* out_value);
90501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
91501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown/*
92501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * Loads information needed for examining a remote process using ptrace().
93501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * The caller must already have successfully attached to the process
94501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * using ptrace().
95501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown *
96501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * The context can be used for any threads belonging to that process
97501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * assuming ptrace() is attached to them before performing the actual
98501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * unwinding.  The context can continue to be used to decode backtraces
99501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * even after ptrace() has been detached from the process.
100501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown */
101501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brownptrace_context_t* load_ptrace_context(pid_t pid);
102501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
103501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown/*
104501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * Frees a ptrace context.
105501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown */
106501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brownvoid free_ptrace_context(ptrace_context_t* context);
107501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
108501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown/*
109501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * Finds a symbol using ptrace.
110501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * Returns the containing map and information about the symbol, or
111501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown * NULL if one or the other is not available.
112501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown */
113501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brownvoid find_symbol_ptrace(const ptrace_context_t* context,
114501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown        uintptr_t addr, const map_info_t** out_map_info, const symbol_t** out_symbol);
115501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
116501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#ifdef __cplusplus
117501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown}
118501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#endif
119501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown
120501edd29b823ce1301d2effdd3a9e4b6e2b20b76Jeff Brown#endif // _CORKSCREW_PTRACE_H
121