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