gdb/target/target.h

   1 /* Declarations for common target functions.
   2
   3    Copyright (C) 1986-2022 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
  37 extern 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
  49 extern 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
  56 extern 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
  77 extern 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
  90 extern 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
  98 extern 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
 103 extern 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
 108 extern 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
 119 extern 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
 124 extern void target_mourn_inferior (ptid_t ptid);
 125
 126 /* Return 1 if this target can debug multiple processes
 127    simultaneously, zero otherwise.  */
 128
 129 extern int target_supports_multi_process (void);
 130
 131 /* Possible terminal states.  */
 132
 133 enum 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.  */
 147 class target_terminal
 148 {
 149 public:
 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
 204 public:
 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
 240 private:
 241
 242   static target_terminal_state m_terminal_state;
 243 };
 244
 245 #endif /* TARGET_TARGET_H */