target.h revision 1.8
1/* Declarations for common target functions. 2 3 Copyright (C) 1986-2023 Free Software Foundation, Inc. 4 5 This file is part of GDB. 6 7 This program is free software; you can redistribute it and/or modify 8 it under the terms of the GNU General Public License as published by 9 the Free Software Foundation; either version 3 of the License, or 10 (at your option) any later version. 11 12 This program is distributed in the hope that it will be useful, 13 but WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 GNU General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 19 20#ifndef TARGET_TARGET_H 21#define TARGET_TARGET_H 22 23#include "target/waitstatus.h" 24#include "target/wait.h" 25 26/* This header is a stopgap until more code is shared. */ 27 28/* Read LEN bytes of target memory at address MEMADDR, placing the 29 results in GDB's memory at MYADDR. Return zero for success, 30 nonzero if any error occurs. This function must be provided by 31 the client. Implementations of this function may define and use 32 their own error codes, but functions in the common, nat and target 33 directories must treat the return code as opaque. No guarantee is 34 made about the contents of the data at MYADDR if any error 35 occurs. */ 36 37extern int target_read_memory (CORE_ADDR memaddr, gdb_byte *myaddr, 38 ssize_t len); 39 40/* Read an unsigned 32-bit integer in the target's format from target 41 memory at address MEMADDR, storing the result in GDB's format in 42 GDB's memory at RESULT. Return zero for success, nonzero if any 43 error occurs. This function must be provided by the client. 44 Implementations of this function may define and use their own error 45 codes, but functions in the common, nat and target directories must 46 treat the return code as opaque. No guarantee is made about the 47 contents of the data at RESULT if any error occurs. */ 48 49extern int target_read_uint32 (CORE_ADDR memaddr, uint32_t *result); 50 51/* Read a string from target memory at address MEMADDR. The string 52 will be at most LEN bytes long (note that excess bytes may be read 53 in some cases -- but these will not be returned). Returns nullptr 54 on error. */ 55 56extern gdb::unique_xmalloc_ptr<char> target_read_string 57 (CORE_ADDR memaddr, int len, int *bytes_read = nullptr); 58 59/* Read a string from the inferior, at ADDR, with LEN characters of 60 WIDTH bytes each. Fetch at most FETCHLIMIT characters. BUFFER 61 will be set to a newly allocated buffer containing the string, and 62 BYTES_READ will be set to the number of bytes read. Returns 0 on 63 success, or a target_xfer_status on failure. 64 65 If LEN > 0, reads the lesser of LEN or FETCHLIMIT characters 66 (including eventual NULs in the middle or end of the string). 67 68 If LEN is -1, stops at the first null character (not necessarily 69 the first null byte) up to a maximum of FETCHLIMIT characters. Set 70 FETCHLIMIT to UINT_MAX to read as many characters as possible from 71 the string. 72 73 Unless an exception is thrown, BUFFER will always be allocated, even on 74 failure. In this case, some characters might have been read before the 75 failure happened. Check BYTES_READ to recognize this situation. */ 76 77extern int target_read_string (CORE_ADDR addr, int len, int width, 78 unsigned int fetchlimit, 79 gdb::unique_xmalloc_ptr<gdb_byte> *buffer, 80 int *bytes_read); 81 82/* Write LEN bytes from MYADDR to target memory at address MEMADDR. 83 Return zero for success, nonzero if any error occurs. This 84 function must be provided by the client. Implementations of this 85 function may define and use their own error codes, but functions 86 in the common, nat and target directories must treat the return 87 code as opaque. No guarantee is made about the contents of the 88 data at MEMADDR if any error occurs. */ 89 90extern int target_write_memory (CORE_ADDR memaddr, const gdb_byte *myaddr, 91 ssize_t len); 92 93/* Cause the target to stop in a continuable fashion--for instance, 94 under Unix, this should act like SIGSTOP--and wait for the target 95 to be stopped before returning. This function must be provided by 96 the client. */ 97 98extern void target_stop_and_wait (ptid_t ptid); 99 100/* Restart a target previously stopped. No signal is delivered to the 101 target. This function must be provided by the client. */ 102 103extern void target_continue_no_signal (ptid_t ptid); 104 105/* Restart a target previously stopped. SIGNAL is delivered to the 106 target. This function must be provided by the client. */ 107 108extern void target_continue (ptid_t ptid, enum gdb_signal signal); 109 110/* Wait for process pid to do something. PTID = -1 to wait for any 111 pid to do something. Return pid of child, or -1 in case of error; 112 store status through argument pointer STATUS. Note that it is 113 _NOT_ OK to throw_exception() out of target_wait() without popping 114 the debugging target from the stack; GDB isn't prepared to get back 115 to the prompt with a debugging target but without the frame cache, 116 stop_pc, etc., set up. OPTIONS is a bitwise OR of TARGET_W* 117 options. */ 118 119extern ptid_t target_wait (ptid_t ptid, struct target_waitstatus *status, 120 target_wait_flags options); 121 122/* The inferior process has died. Do what is right. */ 123 124extern void target_mourn_inferior (ptid_t ptid); 125 126/* Return 1 if this target can debug multiple processes 127 simultaneously, zero otherwise. */ 128 129extern int target_supports_multi_process (void); 130 131/* Possible terminal states. */ 132 133enum class target_terminal_state 134 { 135 /* The inferior's terminal settings are in effect. */ 136 is_inferior = 0, 137 138 /* Some of our terminal settings are in effect, enough to get 139 proper output. */ 140 is_ours_for_output = 1, 141 142 /* Our terminal settings are in effect, for output and input. */ 143 is_ours = 2 144 }; 145 146/* Represents the state of the target terminal. */ 147class target_terminal 148{ 149public: 150 151 target_terminal () = delete; 152 ~target_terminal () = delete; 153 DISABLE_COPY_AND_ASSIGN (target_terminal); 154 155 /* Initialize the terminal settings we record for the inferior, 156 before we actually run the inferior. */ 157 static void init (); 158 159 /* Put the current inferior's terminal settings into effect. This 160 is preparation for starting or resuming the inferior. This is a 161 no-op unless called with the main UI as current UI. */ 162 static void inferior (); 163 164 /* Put our terminal settings into effect. First record the inferior's 165 terminal settings so they can be restored properly later. This is 166 a no-op unless called with the main UI as current UI. */ 167 static void ours (); 168 169 /* Put some of our terminal settings into effect, enough to get proper 170 results from our output, but do not change into or out of RAW mode 171 so that no input is discarded. This is a no-op if terminal_ours 172 was most recently called. This is a no-op unless called with the main 173 UI as current UI. */ 174 static void ours_for_output (); 175 176 /* Restore terminal settings of inferiors that are in 177 is_ours_for_output state back to "inferior". Used when we need 178 to temporarily switch to is_ours_for_output state. */ 179 static void restore_inferior (); 180 181 /* Returns true if the terminal settings of the inferior are in 182 effect. */ 183 static bool is_inferior () 184 { 185 return m_terminal_state == target_terminal_state::is_inferior; 186 } 187 188 /* Returns true if our terminal settings are in effect. */ 189 static bool is_ours () 190 { 191 return m_terminal_state == target_terminal_state::is_ours; 192 } 193 194 /* Returns true if our terminal settings are in effect. */ 195 static bool is_ours_for_output () 196 { 197 return m_terminal_state == target_terminal_state::is_ours_for_output; 198 } 199 200 /* Print useful information about our terminal status, if such a thing 201 exists. */ 202 static void info (const char *arg, int from_tty); 203 204public: 205 206 /* A class that restores the state of the terminal to the current 207 state. */ 208 class scoped_restore_terminal_state 209 { 210 public: 211 212 scoped_restore_terminal_state () 213 : m_state (m_terminal_state) 214 { 215 } 216 217 ~scoped_restore_terminal_state () 218 { 219 switch (m_state) 220 { 221 case target_terminal_state::is_ours: 222 ours (); 223 break; 224 case target_terminal_state::is_ours_for_output: 225 ours_for_output (); 226 break; 227 case target_terminal_state::is_inferior: 228 restore_inferior (); 229 break; 230 } 231 } 232 233 DISABLE_COPY_AND_ASSIGN (scoped_restore_terminal_state); 234 235 private: 236 237 target_terminal_state m_state; 238 }; 239 240private: 241 242 static target_terminal_state m_terminal_state; 243}; 244 245#endif /* TARGET_TARGET_H */ 246