xref: /netbsd-src/external/gpl3/gdb.old/dist/gdb/target-descriptions.h (revision 0a3071956a3a9fdebdbf7f338cf2d439b45fc728)
1 /* Target description support for GDB.
2 
3    Copyright (C) 2006-2020 Free Software Foundation, Inc.
4 
5    Contributed by CodeSourcery.
6 
7    This file is part of GDB.
8 
9    This program is free software; you can redistribute it and/or modify
10    it under the terms of the GNU General Public License as published by
11    the Free Software Foundation; either version 3 of the License, or
12    (at your option) any later version.
13 
14    This program is distributed in the hope that it will be useful,
15    but WITHOUT ANY WARRANTY; without even the implied warranty of
16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17    GNU General Public License for more details.
18 
19    You should have received a copy of the GNU General Public License
20    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
21 
22 #ifndef TARGET_DESCRIPTIONS_H
23 #define TARGET_DESCRIPTIONS_H 1
24 #include "gdbsupport/tdesc.h"
25 #include "gdbarch.h"
26 
27 struct tdesc_arch_data;
28 struct target_ops;
29 /* An inferior's target description info is stored in this opaque
30    object.  There's one such object per inferior.  */
31 struct target_desc_info;
32 struct inferior;
33 
34 /* Fetch the current inferior's description, and switch its current
35    architecture to one which incorporates that description.  */
36 
37 void target_find_description (void);
38 
39 /* Discard any description fetched from the target for the current
40    inferior, and switch the current architecture to one with no target
41    description.  */
42 
43 void target_clear_description (void);
44 
45 /* Return the current inferior's target description.  This should only
46    be used by gdbarch initialization code; most access should be
47    through an existing gdbarch.  */
48 
49 const struct target_desc *target_current_description (void);
50 
51 /* Copy inferior target description data.  Used for example when
52    handling (v)forks, where child's description is the same as the
53    parent's, since the child really is a copy of the parent.  */
54 
55 void copy_inferior_target_desc_info (struct inferior *destinf,
56 				     struct inferior *srcinf);
57 
58 /* Free a target_desc_info object.  */
59 
60 void target_desc_info_free (struct target_desc_info *tdesc_info);
61 
62 /* Returns true if INFO indicates the target description had been
63    supplied by the user.  */
64 
65 int target_desc_info_from_user_p (struct target_desc_info *info);
66 
67 /* Record architecture-specific functions to call for pseudo-register
68    support.  If tdesc_use_registers is called and gdbarch_num_pseudo_regs
69    is greater than zero, then these should be called as well.
70    They are equivalent to the gdbarch methods with similar names,
71    except that they will only be called for pseudo registers.  */
72 
73 void set_tdesc_pseudo_register_name
74   (struct gdbarch *gdbarch, gdbarch_register_name_ftype *pseudo_name);
75 
76 void set_tdesc_pseudo_register_type
77   (struct gdbarch *gdbarch, gdbarch_register_type_ftype *pseudo_type);
78 
79 void set_tdesc_pseudo_register_reggroup_p
80   (struct gdbarch *gdbarch,
81    gdbarch_register_reggroup_p_ftype *pseudo_reggroup_p);
82 
83 /* Pointer to a function that should be called for each unknown register in
84    a target description, used by TDESC_USE_REGISTERS.
85 
86    GDBARCH is the architecture the target description is for, FEATURE is
87    the feature the unknown register is in, and REG_NAME is the name of the
88    register from the target description.  The POSSIBLE_REGNUM is a proposed
89    (GDB internal) number for this register.
90 
91    The callback function can return, (-1) to indicate that the register
92    should not be assigned POSSIBLE_REGNUM now (though it might be later),
93    GDB will number the register automatically later on.  Return
94    POSSIBLE_REGNUM (or greater) to have this register assigned that number.
95    Returning a value less that POSSIBLE_REGNUM is also acceptable, but take
96    care not to clash with a register number that has already been
97    assigned.
98 
99    The callback will always be called on the registers in the order they
100    appear in the target description.  This means all unknown registers
101    within a single feature will be called one after another.  */
102 
103 typedef int (*tdesc_unknown_register_ftype)
104 	(struct gdbarch *gdbarch, tdesc_feature *feature,
105 	 const char *reg_name, int possible_regnum);
106 
107 /* Update GDBARCH to use the TARGET_DESC for registers.  TARGET_DESC
108    may be GDBARCH's target description or (if GDBARCH does not have
109    one which describes registers) another target description
110    constructed by the gdbarch initialization routine.
111 
112    Fixed register assignments are taken from EARLY_DATA, which is freed.
113    All registers which have not been assigned fixed numbers are given
114    numbers above the current value of gdbarch_num_regs.
115    gdbarch_num_regs and various  register-related predicates are updated to
116    refer to the target description.  This function should only be called from
117    the architecture's gdbarch initialization routine, and only after
118    successfully validating the required registers.  */
119 
120 void tdesc_use_registers (struct gdbarch *gdbarch,
121 			  const struct target_desc *target_desc,
122 			  struct tdesc_arch_data *early_data,
123 			  tdesc_unknown_register_ftype unk_reg_cb = NULL);
124 
125 /* Allocate initial data for validation of a target description during
126    gdbarch initialization.  */
127 
128 struct tdesc_arch_data *tdesc_data_alloc (void);
129 
130 /* Clean up data allocated by tdesc_data_alloc.  This should only
131    be called to discard the data; tdesc_use_registers takes ownership
132    of its EARLY_DATA argument.  */
133 
134 void tdesc_data_cleanup (void *data_untyped);
135 
136 /* Search FEATURE for a register named NAME.  Record REGNO and the
137    register in DATA; when tdesc_use_registers is called, REGNO will be
138    assigned to the register.  1 is returned if the register was found,
139    0 if it was not.  */
140 
141 int tdesc_numbered_register (const struct tdesc_feature *feature,
142 			     struct tdesc_arch_data *data,
143 			     int regno, const char *name);
144 
145 /* Search FEATURE for a register named NAME, but do not assign a fixed
146    register number to it.  */
147 
148 int tdesc_unnumbered_register (const struct tdesc_feature *feature,
149 			       const char *name);
150 
151 /* Search FEATURE for a register named NAME, and return its size in
152    bits.  The register must exist.  */
153 
154 int tdesc_register_bitsize (const struct tdesc_feature *feature,
155 			    const char *name);
156 
157 /* Search FEATURE for a register with any of the names from NAMES
158    (NULL-terminated).  Record REGNO and the register in DATA; when
159    tdesc_use_registers is called, REGNO will be assigned to the
160    register.  1 is returned if the register was found, 0 if it was
161    not.  */
162 
163 int tdesc_numbered_register_choices (const struct tdesc_feature *feature,
164 				     struct tdesc_arch_data *data,
165 				     int regno, const char *const names[]);
166 
167 
168 /* Accessors for target descriptions.  */
169 
170 /* Return the BFD architecture associated with this target
171    description, or NULL if no architecture was specified.  */
172 
173 const struct bfd_arch_info *tdesc_architecture
174   (const struct target_desc *);
175 
176 /* Return the OSABI associated with this target description, or
177    GDB_OSABI_UNKNOWN if no osabi was specified.  */
178 
179 enum gdb_osabi tdesc_osabi (const struct target_desc *);
180 
181 /* Return non-zero if this target description is compatible
182    with the given BFD architecture.  */
183 
184 int tdesc_compatible_p (const struct target_desc *,
185 			const struct bfd_arch_info *);
186 
187 /* Return the string value of a property named KEY, or NULL if the
188    property was not specified.  */
189 
190 const char *tdesc_property (const struct target_desc *,
191 			    const char *key);
192 
193 /* Return 1 if this target description describes any registers.  */
194 
195 int tdesc_has_registers (const struct target_desc *);
196 
197 /* Return the feature with the given name, if present, or NULL if
198    the named feature is not found.  */
199 
200 const struct tdesc_feature *tdesc_find_feature (const struct target_desc *,
201 						const char *name);
202 
203 /* Return the name of FEATURE.  */
204 
205 const char *tdesc_feature_name (const struct tdesc_feature *feature);
206 
207 /* Return the name of register REGNO, from the target description or
208    from an architecture-provided pseudo_register_name method.  */
209 
210 const char *tdesc_register_name (struct gdbarch *gdbarch, int regno);
211 
212 /* Return the type of register REGNO, from the target description or
213    from an architecture-provided pseudo_register_type method.  */
214 
215 struct type *tdesc_register_type (struct gdbarch *gdbarch, int regno);
216 
217 /* Return the type associated with ID, from the target description.  */
218 
219 struct type *tdesc_find_type (struct gdbarch *gdbarch, const char *id);
220 
221 /* Check whether REGNUM is a member of REGGROUP using the target
222    description.  Return -1 if the target description does not
223    specify a group.  */
224 
225 int tdesc_register_in_reggroup_p (struct gdbarch *gdbarch, int regno,
226 				  struct reggroup *reggroup);
227 
228 /* Methods for constructing a target description.  */
229 
230 void set_tdesc_architecture (struct target_desc *,
231 			     const struct bfd_arch_info *);
232 void set_tdesc_osabi (struct target_desc *, enum gdb_osabi osabi);
233 void set_tdesc_property (struct target_desc *,
234 			 const char *key, const char *value);
235 void tdesc_add_compatible (struct target_desc *,
236 			   const struct bfd_arch_info *);
237 
238 #if GDB_SELF_TEST
239 namespace selftests {
240 
241 /* Record that XML_FILE should generate a target description that equals
242    TDESC, to be verified by the "maintenance check xml-descriptions"
243    command.  This function takes ownership of TDESC.  */
244 
245 void record_xml_tdesc (const char *xml_file,
246 		       const struct target_desc *tdesc);
247 }
248 #endif
249 
250 #endif /* TARGET_DESCRIPTIONS_H */
251