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 /* Write LEN bytes from MYADDR to target memory at address MEMADDR.
  52    Return zero for success, nonzero if any error occurs.  This
  53    function must be provided by the client.  Implementations of this
  54    function may define and use their own error codes, but functions
  55    in the common, nat and target directories must treat the return
  56    code as opaque.  No guarantee is made about the contents of the
  57    data at MEMADDR if any error occurs.  */
  58
  59 extern int target_write_memory (CORE_ADDR memaddr, const gdb_byte *myaddr,
  60                                 ssize_t len);
  61
  62 /* Cause the target to stop in a continuable fashion--for instance,
  63    under Unix, this should act like SIGSTOP--and wait for the target
  64    to be stopped before returning.  This function must be provided by
  65    the client.  */
  66
  67 extern void target_stop_and_wait (ptid_t ptid);
  68
  69 /* Restart a target previously stopped.  No signal is delivered to the
  70    target.  This function must be provided by the client.  */
  71
  72 extern void target_continue_no_signal (ptid_t ptid);
  73
  74 /* Restart a target previously stopped.  SIGNAL is delivered to the
  75    target.  This function must be provided by the client.  */
  76
  77 extern void target_continue (ptid_t ptid, enum gdb_signal signal);
  78
  79 /* Wait for process pid to do something.  PTID = -1 to wait for any
  80    pid to do something.  Return pid of child, or -1 in case of error;
  81    store status through argument pointer STATUS.  Note that it is
  82    _NOT_ OK to throw_exception() out of target_wait() without popping
  83    the debugging target from the stack; GDB isn't prepared to get back
  84    to the prompt with a debugging target but without the frame cache,
  85    stop_pc, etc., set up.  OPTIONS is a bitwise OR of TARGET_W*
  86    options.  */
  87
  88 extern ptid_t target_wait (ptid_t ptid, struct target_waitstatus *status,
  89                            target_wait_flags options);
  90
  91 /* The inferior process has died.  Do what is right.  */
  92
  93 extern void target_mourn_inferior (ptid_t ptid);
  94
  95 /* Return 1 if this target can debug multiple processes
  96    simultaneously, zero otherwise.  */
  97
  98 extern int target_supports_multi_process (void);
  99
 100 /* Possible terminal states.  */
 101
 102 enum class target_terminal_state
 103   {
 104     /* The inferior's terminal settings are in effect.  */
 105     is_inferior = 0,
 106
 107     /* Some of our terminal settings are in effect, enough to get
 108        proper output.  */
 109     is_ours_for_output = 1,
 110
 111     /* Our terminal settings are in effect, for output and input.  */
 112     is_ours = 2
 113   };
 114
 115 /* Represents the state of the target terminal.  */
 116 class target_terminal
 117 {
 118 public:
 119
 120   target_terminal () = delete;
 121   ~target_terminal () = delete;
 122   DISABLE_COPY_AND_ASSIGN (target_terminal);
 123
 124   /* Initialize the terminal settings we record for the inferior,
 125      before we actually run the inferior.  */
 126   static void init ();
 127
 128   /* Put the current inferior's terminal settings into effect.  This
 129      is preparation for starting or resuming the inferior.  This is a
 130      no-op unless called with the main UI as current UI.  */
 131   static void inferior ();
 132
 133   /* Put our terminal settings into effect.  First record the inferior's
 134      terminal settings so they can be restored properly later.  This is
 135      a no-op unless called with the main UI as current UI.  */
 136   static void ours ();
 137
 138   /* Put some of our terminal settings into effect, enough to get proper
 139      results from our output, but do not change into or out of RAW mode
 140      so that no input is discarded.  This is a no-op if terminal_ours
 141      was most recently called.  This is a no-op unless called with the main
 142      UI as current UI.  */
 143   static void ours_for_output ();
 144
 145   /* Restore terminal settings of inferiors that are in
 146      is_ours_for_output state back to "inferior".  Used when we need
 147      to temporarily switch to is_ours_for_output state.  */
 148   static void restore_inferior ();
 149
 150   /* Returns true if the terminal settings of the inferior are in
 151      effect.  */
 152   static bool is_inferior ()
 153   {
 154     return m_terminal_state == target_terminal_state::is_inferior;
 155   }
 156
 157   /* Returns true if our terminal settings are in effect.  */
 158   static bool is_ours ()
 159   {
 160     return m_terminal_state == target_terminal_state::is_ours;
 161   }
 162
 163   /* Returns true if our terminal settings are in effect.  */
 164   static bool is_ours_for_output ()
 165   {
 166     return m_terminal_state == target_terminal_state::is_ours_for_output;
 167   }
 168
 169   /* Print useful information about our terminal status, if such a thing
 170      exists.  */
 171   static void info (const char *arg, int from_tty);
 172
 173 public:
 174
 175   /* A class that restores the state of the terminal to the current
 176      state.  */
 177   class scoped_restore_terminal_state
 178   {
 179   public:
 180
 181     scoped_restore_terminal_state ()
 182       : m_state (m_terminal_state)
 183     {
 184     }
 185
 186     ~scoped_restore_terminal_state ()
 187     {
 188       switch (m_state)
 189         {
 190         case target_terminal_state::is_ours:
 191           ours ();
 192           break;
 193         case target_terminal_state::is_ours_for_output:
 194           ours_for_output ();
 195           break;
 196         case target_terminal_state::is_inferior:
 197           restore_inferior ();
 198           break;
 199         }
 200     }
 201
 202     DISABLE_COPY_AND_ASSIGN (scoped_restore_terminal_state);
 203
 204   private:
 205
 206     target_terminal_state m_state;
 207   };
 208
 209 private:
 210
 211   static target_terminal_state m_terminal_state;
 212 };
 213
 214 #endif /* TARGET_TARGET_H */