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