[deliverable/binutils-gdb.git] / gdb / target-descriptions.h

/* Target description support for GDB.

   Copyright (C) 2006-2020 Free Software Foundation, Inc.

   Contributed by CodeSourcery.

   This file is part of GDB.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */

#ifndef TARGET_DESCRIPTIONS_H
#define TARGET_DESCRIPTIONS_H 1
#include "gdbsupport/tdesc.h"
#include "gdbarch.h"

struct tdesc_arch_data;
struct target_ops;
/* An inferior's target description info is stored in this opaque
   object.  There's one such object per inferior.  */
struct target_desc_info;
struct inferior;

/* Fetch the current inferior's description, and switch its current
   architecture to one which incorporates that description.  */

void target_find_description (void);

/* Discard any description fetched from the target for the current
   inferior, and switch the current architecture to one with no target
   description.  */

void target_clear_description (void);

/* Return the current inferior's target description.  This should only
   be used by gdbarch initialization code; most access should be
   through an existing gdbarch.  */

const struct target_desc *target_current_description (void);

/* Copy inferior target description data.  Used for example when
   handling (v)forks, where child's description is the same as the
   parent's, since the child really is a copy of the parent.  */

void copy_inferior_target_desc_info (struct inferior *destinf,
				     struct inferior *srcinf);

/* Free a target_desc_info object.  */

void target_desc_info_free (struct target_desc_info *tdesc_info);

/* Returns true if INFO indicates the target description had been
   supplied by the user.  */

int target_desc_info_from_user_p (struct target_desc_info *info);

/* Record architecture-specific functions to call for pseudo-register
   support.  If tdesc_use_registers is called and gdbarch_num_pseudo_regs
   is greater than zero, then these should be called as well.
   They are equivalent to the gdbarch methods with similar names,
   except that they will only be called for pseudo registers.  */

void set_tdesc_pseudo_register_name
  (struct gdbarch *gdbarch, gdbarch_register_name_ftype *pseudo_name);

void set_tdesc_pseudo_register_type
  (struct gdbarch *gdbarch, gdbarch_register_type_ftype *pseudo_type);

void set_tdesc_pseudo_register_reggroup_p
  (struct gdbarch *gdbarch,
   gdbarch_register_reggroup_p_ftype *pseudo_reggroup_p);

/* Update GDBARCH to use the TARGET_DESC for registers.  TARGET_DESC
   may be GDBARCH's target description or (if GDBARCH does not have
   one which describes registers) another target description
   constructed by the gdbarch initialization routine.

   Fixed register assignments are taken from EARLY_DATA, which is freed.
   All registers which have not been assigned fixed numbers are given
   numbers above the current value of gdbarch_num_regs.
   gdbarch_num_regs and various  register-related predicates are updated to
   refer to the target description.  This function should only be called from
   the architecture's gdbarch initialization routine, and only after
   successfully validating the required registers.  */

void tdesc_use_registers (struct gdbarch *gdbarch,
			  const struct target_desc *target_desc,
			  struct tdesc_arch_data *early_data);

/* Allocate initial data for validation of a target description during
   gdbarch initialization.  */

struct tdesc_arch_data *tdesc_data_alloc (void);

/* Clean up data allocated by tdesc_data_alloc.  This should only
   be called to discard the data; tdesc_use_registers takes ownership
   of its EARLY_DATA argument.  */

void tdesc_data_cleanup (void *data_untyped);

/* Search FEATURE for a register named NAME.  Record REGNO and the
   register in DATA; when tdesc_use_registers is called, REGNO will be
   assigned to the register.  1 is returned if the register was found,
   0 if it was not.  */

int tdesc_numbered_register (const struct tdesc_feature *feature,
			     struct tdesc_arch_data *data,
			     int regno, const char *name);

/* Search FEATURE for a register named NAME, but do not assign a fixed
   register number to it.  */

int tdesc_unnumbered_register (const struct tdesc_feature *feature,
			       const char *name);

/* Search FEATURE for a register named NAME, and return its size in
   bits.  The register must exist.  */

int tdesc_register_bitsize (const struct tdesc_feature *feature,
			    const char *name);

/* Search FEATURE for a register with any of the names from NAMES
   (NULL-terminated).  Record REGNO and the register in DATA; when
   tdesc_use_registers is called, REGNO will be assigned to the
   register.  1 is returned if the register was found, 0 if it was
   not.  */

int tdesc_numbered_register_choices (const struct tdesc_feature *feature,
				     struct tdesc_arch_data *data,
				     int regno, const char *const names[]);


/* Accessors for target descriptions.  */

/* Return the BFD architecture associated with this target
   description, or NULL if no architecture was specified.  */

const struct bfd_arch_info *tdesc_architecture
  (const struct target_desc *);

/* Return the OSABI associated with this target description, or
   GDB_OSABI_UNKNOWN if no osabi was specified.  */

enum gdb_osabi tdesc_osabi (const struct target_desc *);

/* Return non-zero if this target description is compatible
   with the given BFD architecture.  */

int tdesc_compatible_p (const struct target_desc *,
			const struct bfd_arch_info *);

/* Return the string value of a property named KEY, or NULL if the
   property was not specified.  */

const char *tdesc_property (const struct target_desc *,
			    const char *key);

/* Return 1 if this target description describes any registers.  */

int tdesc_has_registers (const struct target_desc *);

/* Return the feature with the given name, if present, or NULL if
   the named feature is not found.  */

const struct tdesc_feature *tdesc_find_feature (const struct target_desc *,
						const char *name);

/* Return the name of FEATURE.  */

const char *tdesc_feature_name (const struct tdesc_feature *feature);

/* Return the name of register REGNO, from the target description or
   from an architecture-provided pseudo_register_name method.  */

const char *tdesc_register_name (struct gdbarch *gdbarch, int regno);

/* Return the type of register REGNO, from the target description or
   from an architecture-provided pseudo_register_type method.  */

struct type *tdesc_register_type (struct gdbarch *gdbarch, int regno);

/* Return the type associated with ID, from the target description.  */

struct type *tdesc_find_type (struct gdbarch *gdbarch, const char *id);

/* Check whether REGNUM is a member of REGGROUP using the target
   description.  Return -1 if the target description does not
   specify a group.  */

int tdesc_register_in_reggroup_p (struct gdbarch *gdbarch, int regno,
				  struct reggroup *reggroup);


/* A deleter adapter for a target desc.  */

struct target_desc_deleter
{
  void operator() (struct target_desc *desc) const;
};

/* A unique pointer specialization that holds a target_desc.  */

typedef std::unique_ptr<target_desc, target_desc_deleter> target_desc_up;

/* Methods for constructing a target description.  */

void set_tdesc_architecture (struct target_desc *,
			     const struct bfd_arch_info *);
void set_tdesc_osabi (struct target_desc *, enum gdb_osabi osabi);
void set_tdesc_property (struct target_desc *,
			 const char *key, const char *value);
void tdesc_add_compatible (struct target_desc *,
			   const struct bfd_arch_info *);

#if GDB_SELF_TEST
namespace selftests {

/* Record that XML_FILE should generate a target description that equals
   TDESC, to be verified by the "maintenance check xml-descriptions"
   command.  This function takes ownership of TDESC.  */

void record_xml_tdesc (const char *xml_file,
		       const struct target_desc *tdesc);
}
#endif

#endif /* TARGET_DESCRIPTIONS_H */
Commit	Line	Data
424163ea DJ	1	/* Target description support for GDB.
424163ea DJ	2
b811d2c2	3	Copyright (C) 2006-2020 Free Software Foundation, Inc.
424163ea DJ	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
a9762ec7	11	the Free Software Foundation; either version 3 of the License, or
424163ea DJ	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
a9762ec7	20	along with this program. If not, see <http://www.gnu.org/licenses/>. */
424163ea DJ	21
	22	#ifndef TARGET_DESCRIPTIONS_H
	23	#define TARGET_DESCRIPTIONS_H 1
268a13a5	24	#include "gdbsupport/tdesc.h"
0d12e84c	25	#include "gdbarch.h"
424163ea	26
123dc839	27	struct tdesc_arch_data;
123dc839	28	struct target_ops;
6ecd4729 PA	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;
424163ea	33
6ecd4729	34	/* Fetch the current inferior's description, and switch its current
424163ea DJ	35	architecture to one which incorporates that description. */
	36
	37	void target_find_description (void);
	38
6ecd4729 PA	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. */
424163ea DJ	42
	43	void target_clear_description (void);
	44
6ecd4729 PA	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. */
424163ea DJ	48
	49	const struct target_desc *target_current_description (void);
	50
6ecd4729 PA	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
123dc839	67	/* Record architecture-specific functions to call for pseudo-register
f57d151a	68	support. If tdesc_use_registers is called and gdbarch_num_pseudo_regs
123dc839 DJ	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
7cc46491 DJ	83	/* Update GDBARCH to use the TARGET_DESC for registers. TARGET_DESC
	84	may be GDBARCH's target description or (if GDBARCH does not have
	85	one which describes registers) another target description
	86	constructed by the gdbarch initialization routine.
	87
	88	Fixed register assignments are taken from EARLY_DATA, which is freed.
123dc839	89	All registers which have not been assigned fixed numbers are given
f57d151a UW	90	numbers above the current value of gdbarch_num_regs.
	91	gdbarch_num_regs and various register-related predicates are updated to
	92	refer to the target description. This function should only be called from
	93	the architecture's gdbarch initialization routine, and only after
123dc839 DJ	94	successfully validating the required registers. */
	95
	96	void tdesc_use_registers (struct gdbarch *gdbarch,
7cc46491	97	const struct target_desc *target_desc,
123dc839 DJ	98	struct tdesc_arch_data *early_data);
	99
	100	/* Allocate initial data for validation of a target description during
	101	gdbarch initialization. */
	102
	103	struct tdesc_arch_data *tdesc_data_alloc (void);
	104
	105	/* Clean up data allocated by tdesc_data_alloc. This should only
	106	be called to discard the data; tdesc_use_registers takes ownership
	107	of its EARLY_DATA argument. */
	108
	109	void tdesc_data_cleanup (void *data_untyped);
	110
	111	/* Search FEATURE for a register named NAME. Record REGNO and the
	112	register in DATA; when tdesc_use_registers is called, REGNO will be
	113	assigned to the register. 1 is returned if the register was found,
	114	0 if it was not. */
	115
	116	int tdesc_numbered_register (const struct tdesc_feature *feature,
	117	struct tdesc_arch_data *data,
	118	int regno, const char *name);
	119
58d6951d DJ	120	/* Search FEATURE for a register named NAME, but do not assign a fixed
	121	register number to it. */
	122
	123	int tdesc_unnumbered_register (const struct tdesc_feature *feature,
	124	const char *name);
	125
7cc46491 DJ	126	/* Search FEATURE for a register named NAME, and return its size in
	127	bits. The register must exist. */
	128
12863263 AH	129	int tdesc_register_bitsize (const struct tdesc_feature *feature,
12863263 AH	130	const char *name);
7cc46491	131
123dc839 DJ	132	/* Search FEATURE for a register with any of the names from NAMES
	133	(NULL-terminated). Record REGNO and the register in DATA; when
	134	tdesc_use_registers is called, REGNO will be assigned to the
	135	register. 1 is returned if the register was found, 0 if it was
	136	not. */
	137
	138	int tdesc_numbered_register_choices (const struct tdesc_feature *feature,
	139	struct tdesc_arch_data *data,
	140	int regno, const char *const names[]);
	141
	142
424163ea DJ	143	/* Accessors for target descriptions. */
424163ea DJ	144
23181151 DJ	145	/* Return the BFD architecture associated with this target
	146	description, or NULL if no architecture was specified. */
	147
	148	const struct bfd_arch_info *tdesc_architecture
	149	(const struct target_desc *);
	150
08d16641 PA	151	/* Return the OSABI associated with this target description, or
	152	GDB_OSABI_UNKNOWN if no osabi was specified. */
	153
	154	enum gdb_osabi tdesc_osabi (const struct target_desc *);
	155
e35359c5 UW	156	/* Return non-zero if this target description is compatible
	157	with the given BFD architecture. */
	158
	159	int tdesc_compatible_p (const struct target_desc *,
	160	const struct bfd_arch_info *);
	161
29709017 DJ	162	/* Return the string value of a property named KEY, or NULL if the
	163	property was not specified. */
	164
	165	const char tdesc_property (const struct target_desc ,
	166	const char *key);
	167
123dc839 DJ	168	/* Return 1 if this target description describes any registers. */
	169
	170	int tdesc_has_registers (const struct target_desc *);
	171
	172	/* Return the feature with the given name, if present, or NULL if
	173	the named feature is not found. */
	174
	175	const struct tdesc_feature tdesc_find_feature (const struct target_desc ,
	176	const char *name);
	177
	178	/* Return the name of FEATURE. */
	179
	180	const char tdesc_feature_name (const struct tdesc_feature feature);
	181
f8b73d13 DJ	182	/* Return the name of register REGNO, from the target description or
	183	from an architecture-provided pseudo_register_name method. */
	184
d93859e2	185	const char tdesc_register_name (struct gdbarch gdbarch, int regno);
f8b73d13	186
58d6951d DJ	187	/* Return the type of register REGNO, from the target description or
	188	from an architecture-provided pseudo_register_type method. */
	189
	190	struct type tdesc_register_type (struct gdbarch gdbarch, int regno);
	191
c378eb4e	192	/* Return the type associated with ID, from the target description. */
9fd3625f L	193
	194	struct type tdesc_find_type (struct gdbarch gdbarch, const char *id);
	195
f8b73d13 DJ	196	/* Check whether REGNUM is a member of REGGROUP using the target
	197	description. Return -1 if the target description does not
	198	specify a group. */
	199
	200	int tdesc_register_in_reggroup_p (struct gdbarch *gdbarch, int regno,
	201	struct reggroup *reggroup);
	202
c55d06ec TT	203
	204	/* A deleter adapter for a target desc. */
	205
	206	struct target_desc_deleter
	207	{
	208	void operator() (struct target_desc *desc) const;
	209	};
	210
	211	/* A unique pointer specialization that holds a target_desc. */
	212
	213	typedef std::unique_ptr<target_desc, target_desc_deleter> target_desc_up;
	214
424163ea DJ	215	/* Methods for constructing a target description. */
424163ea DJ	216
23181151 DJ	217	void set_tdesc_architecture (struct target_desc *,
23181151 DJ	218	const struct bfd_arch_info *);
08d16641	219	void set_tdesc_osabi (struct target_desc *, enum gdb_osabi osabi);
29709017 DJ	220	void set_tdesc_property (struct target_desc *,
29709017 DJ	221	const char key, const char value);
e35359c5 UW	222	void tdesc_add_compatible (struct target_desc *,
e35359c5 UW	223	const struct bfd_arch_info *);
123dc839	224
27d41eac YQ	225	#if GDB_SELF_TEST
	226	namespace selftests {
	227
	228	/* Record that XML_FILE should generate a target description that equals
	229	TDESC, to be verified by the "maintenance check xml-descriptions"
1c28969e	230	command. This function takes ownership of TDESC. */
27d41eac YQ	231
	232	void record_xml_tdesc (const char *xml_file,
	233	const struct target_desc *tdesc);
	234	}
	235	#endif
	236
424163ea	237	#endif /* TARGET_DESCRIPTIONS_H */