gdb/target/target.h

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