gdb/gdbarch.h

   1 /* Dynamic architecture support for GDB, the GNU debugger.
   2
   3    Copyright (C) 1998-2024 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
  21 #ifndef GDBARCH_H
  22 #define GDBARCH_H
  23
  24 #include <vector>
  25 #include "frame.h"
  26 #include "dis-asm.h"
  27 #include "gdbsupport/gdb_obstack.h"
  28 #include "infrun.h"
  29 #include "osabi.h"
  30 #include "displaced-stepping.h"
  31 #include "gdbsupport/gdb-checked-static-cast.h"
  32 #include "registry.h"
  33
  34 struct floatformat;
  35 struct ui_file;
  36 struct value;
  37 struct objfile;
  38 struct obj_section;
  39 struct minimal_symbol;
  40 struct regcache;
  41 struct reggroup;
  42 struct regset;
  43 struct disassemble_info;
  44 struct target_ops;
  45 struct obstack;
  46 struct bp_target_info;
  47 struct target_desc;
  48 struct symbol;
  49 struct syscall;
  50 struct agent_expr;
  51 struct axs_value;
  52 struct stap_parse_info;
  53 struct expr_builder;
  54 struct ravenscar_arch_ops;
  55 struct mem_range;
  56 struct syscalls_info;
  57 struct thread_info;
  58 struct ui_out;
  59 struct inferior;
  60 struct x86_xsave_layout;
  61
  62 #include "regcache.h"
  63
  64 /* The base class for every architecture's tdep sub-class.  The virtual
  65    destructor ensures the class has RTTI information, which allows
  66    gdb::checked_static_cast to be used in the gdbarch_tdep function.  */
  67
  68 struct gdbarch_tdep_base
  69 {
  70   virtual ~gdbarch_tdep_base() = default;
  71 };
  72
  73 using gdbarch_tdep_up = std::unique_ptr<gdbarch_tdep_base>;
  74
  75 /* Callback type for the 'iterate_over_objfiles_in_search_order'
  76    gdbarch  method.  */
  77
  78 using iterate_over_objfiles_in_search_order_cb_ftype
  79   = gdb::function_view<bool(objfile *)>;
  80
  81 /* Callback type for regset section iterators.  The callback usually
  82    invokes the REGSET's supply or collect method, to which it must
  83    pass a buffer - for collects this buffer will need to be created using
  84    COLLECT_SIZE, for supply the existing buffer being read from should
  85    be at least SUPPLY_SIZE.  SECT_NAME is a BFD section name, and HUMAN_NAME
  86    is used for diagnostic messages.  CB_DATA should have been passed
  87    unchanged through the iterator.  */
  88
  89 typedef void (iterate_over_regset_sections_cb)
  90   (const char *sect_name, int supply_size, int collect_size,
  91    const struct regset *regset, const char *human_name, void *cb_data);
  92
  93 /* For a function call, does the function return a value using a
  94    normal value return or a structure return - passing a hidden
  95    argument pointing to storage.  For the latter, there are two
  96    cases: language-mandated structure return and target ABI
  97    structure return.  */
  98
  99 enum function_call_return_method
 100 {
 101   /* Standard value return.  */
 102   return_method_normal = 0,
 103
 104   /* Language ABI structure return.  This is handled
 105      by passing the return location as the first parameter to
 106      the function, even preceding "this".  */
 107   return_method_hidden_param,
 108
 109   /* Target ABI struct return.  This is target-specific; for instance,
 110      on ia64 the first argument is passed in out0 but the hidden
 111      structure return pointer would normally be passed in r8.  */
 112   return_method_struct,
 113 };
 114
 115 enum class memtag_type
 116 {
 117   /* Logical tag, the tag that is stored in unused bits of a pointer to a
 118      virtual address.  */
 119   logical = 0,
 120
 121   /* Allocation tag, the tag that is associated with every granule of memory in
 122      the physical address space.  Allocation tags are used to validate memory
 123      accesses via pointers containing logical tags.  */
 124   allocation,
 125 };
 126
 127 /* Callback types for 'read_core_file_mappings' gdbarch method.  */
 128
 129 using read_core_file_mappings_pre_loop_ftype =
 130   gdb::function_view<void (ULONGEST count)>;
 131
 132 using read_core_file_mappings_loop_ftype =
 133   gdb::function_view<void (int num,
 134                            ULONGEST start,
 135                            ULONGEST end,
 136                            ULONGEST file_ofs,
 137                            const char *filename,
 138                            const bfd_build_id *build_id)>;
 139
 140 /* Possible values for gdbarch_call_dummy_location.  */
 141 enum call_dummy_location_type
 142 {
 143   ON_STACK,
 144   AT_ENTRY_POINT,
 145 };
 146
 147 #include "gdbarch-gen.h"
 148
 149 /* An internal function that should _only_ be called from gdbarch_tdep.
 150    Returns the gdbarch_tdep_base field held within GDBARCH.  */
 151
 152 extern struct gdbarch_tdep_base *gdbarch_tdep_1 (struct gdbarch *gdbarch);
 153
 154 /* Return the gdbarch_tdep_base object held within GDBARCH cast to the type
 155    TDepType, which should be a sub-class of gdbarch_tdep_base.
 156
 157    When GDB is compiled in maintainer mode a run-time check is performed
 158    that the gdbarch_tdep_base within GDBARCH really is of type TDepType.
 159    When GDB is compiled in release mode the run-time check is not
 160    performed, and we assume the caller knows what they are doing.  */
 161
 162 template<typename TDepType>
 163 static inline TDepType *
 164 gdbarch_tdep (struct gdbarch *gdbarch)
 165 {
 166   struct gdbarch_tdep_base *tdep = gdbarch_tdep_1 (gdbarch);
 167   return gdb::checked_static_cast<TDepType *> (tdep);
 168 }
 169
 170 /* Mechanism for co-ordinating the selection of a specific
 171    architecture.
 172
 173    GDB targets (*-tdep.c) can register an interest in a specific
 174    architecture.  Other GDB components can register a need to maintain
 175    per-architecture data.
 176
 177    The mechanisms below ensures that there is only a loose connection
 178    between the set-architecture command and the various GDB
 179    components.  Each component can independently register their need
 180    to maintain architecture specific data with gdbarch.
 181
 182    Pragmatics:
 183
 184    Previously, a single TARGET_ARCHITECTURE_HOOK was provided.  It
 185    didn't scale.
 186
 187    The more traditional mega-struct containing architecture specific
 188    data for all the various GDB components was also considered.  Since
 189    GDB is built from a variable number of (fairly independent)
 190    components it was determined that the global approach was not
 191    applicable.  */
 192
 193
 194 /* Register a new architectural family with GDB.
 195
 196    Register support for the specified ARCHITECTURE with GDB.  When
 197    gdbarch determines that the specified architecture has been
 198    selected, the corresponding INIT function is called.
 199
 200    --
 201
 202    The INIT function takes two parameters: INFO which contains the
 203    information available to gdbarch about the (possibly new)
 204    architecture; ARCHES which is a list of the previously created
 205    ``struct gdbarch'' for this architecture.
 206
 207    The INFO parameter is, as far as possible, be pre-initialized with
 208    information obtained from INFO.ABFD or the global defaults.
 209
 210    The ARCHES parameter is a linked list (sorted most recently used)
 211    of all the previously created architures for this architecture
 212    family.  The (possibly NULL) ARCHES->gdbarch can used to access
 213    values from the previously selected architecture for this
 214    architecture family.
 215
 216    The INIT function shall return any of: NULL - indicating that it
 217    doesn't recognize the selected architecture; an existing ``struct
 218    gdbarch'' from the ARCHES list - indicating that the new
 219    architecture is just a synonym for an earlier architecture (see
 220    gdbarch_list_lookup_by_info()); a newly created ``struct gdbarch''
 221    - that describes the selected architecture (see gdbarch_alloc()).
 222
 223    The DUMP_TDEP function shall print out all target specific values.
 224    Care should be taken to ensure that the function works in both the
 225    multi-arch and non- multi-arch cases.  */
 226
 227 struct gdbarch_list
 228 {
 229   struct gdbarch *gdbarch;
 230   struct gdbarch_list *next;
 231 };
 232
 233 struct gdbarch_info
 234 {
 235   const struct bfd_arch_info *bfd_arch_info = nullptr;
 236
 237   enum bfd_endian byte_order = BFD_ENDIAN_UNKNOWN;
 238
 239   enum bfd_endian byte_order_for_code = BFD_ENDIAN_UNKNOWN;
 240
 241   bfd *abfd = nullptr;
 242
 243   /* Architecture-specific target description data.  */
 244   struct tdesc_arch_data *tdesc_data = nullptr;
 245
 246   enum gdb_osabi osabi = GDB_OSABI_UNKNOWN;
 247
 248   const struct target_desc *target_desc = nullptr;
 249 };
 250
 251 typedef struct gdbarch *(gdbarch_init_ftype) (struct gdbarch_info info, struct gdbarch_list *arches);
 252 typedef void (gdbarch_dump_tdep_ftype) (struct gdbarch *gdbarch, struct ui_file *file);
 253 typedef bool (gdbarch_supports_arch_info_ftype) (const struct bfd_arch_info *);
 254
 255 extern void gdbarch_register (enum bfd_architecture architecture,
 256                               gdbarch_init_ftype *init,
 257                               gdbarch_dump_tdep_ftype *dump_tdep = nullptr,
 258                               gdbarch_supports_arch_info_ftype *supports_arch_info = nullptr);
 259
 260 /* Return true if ARCH is initialized.  */
 261
 262 bool gdbarch_initialized_p (gdbarch *arch);
 263
 264 /* Return a vector of the valid architecture names.  Since architectures are
 265    registered during the _initialize phase this function only returns useful
 266    information once initialization has been completed.  */
 267
 268 extern std::vector<const char *> gdbarch_printable_names ();
 269
 270
 271 /* Helper function.  Search the list of ARCHES for a GDBARCH that
 272    matches the information provided by INFO.  */
 273
 274 extern struct gdbarch_list *gdbarch_list_lookup_by_info (struct gdbarch_list *arches, const struct gdbarch_info *info);
 275
 276
 277 /* Helper function.  Create a preliminary ``struct gdbarch''.  Perform
 278    basic initialization using values obtained from the INFO and TDEP
 279    parameters.  set_gdbarch_*() functions are called to complete the
 280    initialization of the object.  */
 281
 282 extern struct gdbarch *gdbarch_alloc (const struct gdbarch_info *info,
 283                                       gdbarch_tdep_up tdep);
 284
 285
 286 /* Helper function.  Free a partially-constructed ``struct gdbarch''.
 287    It is assumed that the caller frees the ``struct
 288    gdbarch_tdep''.  */
 289
 290 extern void gdbarch_free (struct gdbarch *);
 291
 292 struct gdbarch_deleter
 293 {
 294   void operator() (gdbarch *arch) const
 295   { gdbarch_free (arch); }
 296 };
 297
 298 using gdbarch_up = std::unique_ptr<gdbarch, gdbarch_deleter>;
 299
 300 /* Get the obstack owned by ARCH.  */
 301
 302 extern obstack *gdbarch_obstack (gdbarch *arch);
 303
 304 /* Helper function.  Allocate memory from the ``struct gdbarch''
 305    obstack.  The memory is freed when the corresponding architecture
 306    is also freed.  */
 307
 308 #define GDBARCH_OBSTACK_CALLOC(GDBARCH, NR, TYPE)   obstack_calloc<TYPE> (gdbarch_obstack ((GDBARCH)), (NR))
 309
 310 #define GDBARCH_OBSTACK_ZALLOC(GDBARCH, TYPE)   obstack_zalloc<TYPE> (gdbarch_obstack ((GDBARCH)))
 311
 312 /* Duplicate STRING, returning an equivalent string that's allocated on the
 313    obstack associated with GDBARCH.  The string is freed when the corresponding
 314    architecture is also freed.  */
 315
 316 extern char *gdbarch_obstack_strdup (struct gdbarch *arch, const char *string);
 317
 318 /* Helper function.  Force an update of the current architecture.
 319
 320    The actual architecture selected is determined by INFO, ``(gdb) set
 321    architecture'' et.al., the existing architecture and BFD's default
 322    architecture.  INFO should be initialized to zero and then selected
 323    fields should be updated.
 324
 325    Returns non-zero if the update succeeds.  */
 326
 327 extern int gdbarch_update_p (struct gdbarch_info info);
 328
 329
 330 /* Helper function.  Find an architecture matching info.
 331
 332    INFO should have relevant fields set, and then finished using
 333    gdbarch_info_fill.
 334
 335    Returns the corresponding architecture, or NULL if no matching
 336    architecture was found.  */
 337
 338 extern struct gdbarch *gdbarch_find_by_info (struct gdbarch_info info);
 339
 340 /* A registry adaptor for gdbarch.  This arranges to store the
 341    registry in the gdbarch.  */
 342 template<>
 343 struct registry_accessor<gdbarch>
 344 {
 345   static registry<gdbarch> *get (gdbarch *arch);
 346 };
 347
 348 /* Set the dynamic target-system-dependent parameters (architecture,
 349    byte-order, ...) using information found in the BFD.  */
 350
 351 extern void set_gdbarch_from_file (bfd *);
 352
 353
 354 /* Initialize the current architecture to the "first" one we find on
 355    our list.  */
 356
 357 extern void initialize_current_architecture (void);
 358
 359 /* gdbarch trace variable */
 360 extern unsigned int gdbarch_debug;
 361
 362 extern void gdbarch_dump (struct gdbarch *gdbarch, struct ui_file *file);
 363
 364 /* Return the number of cooked registers (raw + pseudo) for ARCH.  */
 365
 366 static inline int
 367 gdbarch_num_cooked_regs (gdbarch *arch)
 368 {
 369   return gdbarch_num_regs (arch) + gdbarch_num_pseudo_regs (arch);
 370 }
 371
 372 #endif