gdbsupport/tdesc.h

   1 /* Copyright (C) 2006-2024 Free Software Foundation, Inc.
   2
   3    This file is part of GDB.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  17
  18 #ifndef COMMON_TDESC_H
  19 #define COMMON_TDESC_H
  20
  21 #include "gdbsupport/osabi.h"
  22
  23 struct tdesc_feature;
  24 struct tdesc_type;
  25 struct tdesc_type_builtin;
  26 struct tdesc_type_vector;
  27 struct tdesc_type_with_fields;
  28 struct tdesc_reg;
  29 struct target_desc;
  30
  31 /* The interface to visit different elements of target description.  */
  32
  33 class tdesc_element_visitor
  34 {
  35 public:
  36   virtual void visit_pre (const target_desc *e)
  37   {}
  38
  39   virtual void visit_post (const target_desc *e)
  40   {}
  41
  42   virtual void visit_pre (const tdesc_feature *e)
  43   {}
  44
  45   virtual void visit_post (const tdesc_feature *e)
  46   {}
  47
  48   virtual void visit (const tdesc_type_builtin *e)
  49   {}
  50
  51   virtual void visit (const tdesc_type_vector *e)
  52   {}
  53
  54   virtual void visit (const tdesc_type_with_fields *e)
  55   {}
  56
  57   virtual void visit (const tdesc_reg *e)
  58   {}
  59 };
  60
  61 class tdesc_element
  62 {
  63 public:
  64   virtual void accept (tdesc_element_visitor &v) const = 0;
  65 };
  66
  67 /* An individual register from a target description.  */
  68
  69 struct tdesc_reg : tdesc_element
  70 {
  71   tdesc_reg (struct tdesc_feature *feature, const std::string &name_,
  72              int regnum, int save_restore_, const char *group_,
  73              int bitsize_, const char *type_);
  74
  75   virtual ~tdesc_reg () = default;
  76
  77   DISABLE_COPY_AND_ASSIGN (tdesc_reg);
  78
  79   /* The name of this register.  In standard features, it may be
  80      recognized by the architecture support code, or it may be purely
  81      for the user.  */
  82   std::string name;
  83
  84   /* The register number used by this target to refer to this
  85      register.  This is used for remote p/P packets and to determine
  86      the ordering of registers in the remote g/G packets.  */
  87   long target_regnum;
  88
  89   /* If this flag is set, GDB should save and restore this register
  90      around calls to an inferior function.  */
  91   int save_restore;
  92
  93   /* The name of the register group containing this register, or empty
  94      if the group should be automatically determined from the
  95      register's type.  If this is "general", "float", or "vector", the
  96      corresponding "info" command should display this register's
  97      value.  It can be an arbitrary string, but should be limited to
  98      alphanumeric characters and internal hyphens.  Currently other
  99      strings are ignored (treated as empty).  */
 100   std::string group;
 101
 102   /* The size of the register, in bits.  */
 103   int bitsize;
 104
 105   /* The type of the register.  This string corresponds to either
 106      a named type from the target description or a predefined
 107      type from GDB.  */
 108   std::string type;
 109
 110   /* The target-described type corresponding to TYPE, if found.  */
 111   struct tdesc_type *tdesc_type;
 112
 113   void accept (tdesc_element_visitor &v) const override
 114   {
 115     v.visit (this);
 116   }
 117
 118   bool operator== (const tdesc_reg &other) const
 119   {
 120     return (name == other.name
 121        && target_regnum == other.target_regnum
 122        && save_restore == other.save_restore
 123        && bitsize == other.bitsize
 124        && group == other.group
 125        && type == other.type);
 126   }
 127
 128   bool operator!= (const tdesc_reg &other) const
 129   {
 130     return !(*this == other);
 131   }
 132 };
 133
 134 typedef std::unique_ptr<tdesc_reg> tdesc_reg_up;
 135
 136 /* Declaration of a structure that holds information about one
 137    "compatibility" entry within a target description.  */
 138
 139 struct tdesc_compatible_info;
 140
 141 /* A pointer to a single piece of compatibility information.  */
 142
 143 typedef std::unique_ptr<tdesc_compatible_info> tdesc_compatible_info_up;
 144
 145 /* Return a vector of compatibility information pointers from the target
 146    description TARGET_DESC.  */
 147
 148 const std::vector<tdesc_compatible_info_up> &tdesc_compatible_info_list
 149         (const target_desc *target_desc);
 150
 151 /* Return the architecture name from a compatibility information
 152    COMPATIBLE.  */
 153
 154 const char *tdesc_compatible_info_arch_name
 155         (const tdesc_compatible_info_up &compatible);
 156
 157 enum tdesc_type_kind
 158 {
 159   /* Predefined types.  */
 160   TDESC_TYPE_BOOL,
 161   TDESC_TYPE_INT8,
 162   TDESC_TYPE_INT16,
 163   TDESC_TYPE_INT32,
 164   TDESC_TYPE_INT64,
 165   TDESC_TYPE_INT128,
 166   TDESC_TYPE_UINT8,
 167   TDESC_TYPE_UINT16,
 168   TDESC_TYPE_UINT32,
 169   TDESC_TYPE_UINT64,
 170   TDESC_TYPE_UINT128,
 171   TDESC_TYPE_CODE_PTR,
 172   TDESC_TYPE_DATA_PTR,
 173   TDESC_TYPE_IEEE_HALF,
 174   TDESC_TYPE_IEEE_SINGLE,
 175   TDESC_TYPE_IEEE_DOUBLE,
 176   TDESC_TYPE_ARM_FPA_EXT,
 177   TDESC_TYPE_I387_EXT,
 178   TDESC_TYPE_BFLOAT16,
 179
 180   /* Types defined by a target feature.  */
 181   TDESC_TYPE_VECTOR,
 182   TDESC_TYPE_STRUCT,
 183   TDESC_TYPE_UNION,
 184   TDESC_TYPE_FLAGS,
 185   TDESC_TYPE_ENUM
 186 };
 187
 188 struct tdesc_type : tdesc_element
 189 {
 190   tdesc_type (const std::string &name_, enum tdesc_type_kind kind_)
 191     : name (name_), kind (kind_)
 192   {}
 193
 194   virtual ~tdesc_type () = default;
 195
 196   DISABLE_COPY_AND_ASSIGN (tdesc_type);
 197
 198   /* The name of this type.  */
 199   std::string name;
 200
 201   /* Identify the kind of this type.  */
 202   enum tdesc_type_kind kind;
 203
 204   bool operator== (const tdesc_type &other) const
 205   {
 206     return name == other.name && kind == other.kind;
 207   }
 208
 209   bool operator!= (const tdesc_type &other) const
 210   {
 211     return !(*this == other);
 212   }
 213 };
 214
 215 typedef std::unique_ptr<tdesc_type> tdesc_type_up;
 216
 217 struct tdesc_type_builtin : tdesc_type
 218 {
 219   tdesc_type_builtin (const std::string &name, enum tdesc_type_kind kind)
 220   : tdesc_type (name, kind)
 221   {}
 222
 223   void accept (tdesc_element_visitor &v) const override
 224   {
 225     v.visit (this);
 226   }
 227 };
 228
 229 /* tdesc_type for vector types.  */
 230
 231 struct tdesc_type_vector : tdesc_type
 232 {
 233   tdesc_type_vector (const std::string &name, tdesc_type *element_type_,
 234                      int count_)
 235   : tdesc_type (name, TDESC_TYPE_VECTOR),
 236     element_type (element_type_), count (count_)
 237   {}
 238
 239   void accept (tdesc_element_visitor &v) const override
 240   {
 241     v.visit (this);
 242   }
 243
 244   struct tdesc_type *element_type;
 245   int count;
 246 };
 247
 248 /* A named type from a target description.  */
 249
 250 struct tdesc_type_field
 251 {
 252   tdesc_type_field (const std::string &name_, tdesc_type *type_,
 253                     int start_, int end_)
 254   : name (name_), type (type_), start (start_), end (end_)
 255   {}
 256
 257   std::string name;
 258   struct tdesc_type *type;
 259   /* For non-enum-values, either both are -1 (non-bitfield), or both are
 260      not -1 (bitfield).  For enum values, start is the value (which could be
 261      -1), end is -1.  */
 262   int start, end;
 263 };
 264
 265 /* tdesc_type for struct, union, flags, and enum types.  */
 266
 267 struct tdesc_type_with_fields : tdesc_type
 268 {
 269   tdesc_type_with_fields (const std::string &name, tdesc_type_kind kind,
 270                           int size_ = 0)
 271   : tdesc_type (name, kind), size (size_)
 272   {}
 273
 274   void accept (tdesc_element_visitor &v) const override
 275   {
 276     v.visit (this);
 277   }
 278
 279   std::vector<tdesc_type_field> fields;
 280   int size;
 281 };
 282
 283 /* A feature from a target description.  Each feature is a collection
 284    of other elements, e.g. registers and types.  */
 285
 286 struct tdesc_feature : tdesc_element
 287 {
 288   tdesc_feature (const std::string &name_)
 289     : name (name_)
 290   {}
 291
 292   virtual ~tdesc_feature () = default;
 293
 294   DISABLE_COPY_AND_ASSIGN (tdesc_feature);
 295
 296   /* The name of this feature.  It may be recognized by the architecture
 297      support code.  */
 298   std::string name;
 299
 300   /* The registers associated with this feature.  */
 301   std::vector<tdesc_reg_up> registers;
 302
 303   /* The types associated with this feature.  */
 304   std::vector<tdesc_type_up> types;
 305
 306   void accept (tdesc_element_visitor &v) const override;
 307
 308   bool operator== (const tdesc_feature &other) const;
 309
 310   bool operator!= (const tdesc_feature &other) const
 311   {
 312     return !(*this == other);
 313   }
 314 };
 315
 316 typedef std::unique_ptr<tdesc_feature> tdesc_feature_up;
 317
 318 /* A deleter adapter for a target_desc.  There are different
 319    implementations of this deleter class in gdb and gdbserver because even
 320    though the target_desc name is shared between the two projects, the
 321    actual implementations of target_desc are completely different.  */
 322
 323 struct target_desc_deleter
 324 {
 325   void operator() (struct target_desc *desc) const;
 326 };
 327
 328 /* A unique pointer specialization that holds a target_desc.  */
 329
 330 typedef std::unique_ptr<target_desc, target_desc_deleter> target_desc_up;
 331
 332 /* Allocate a new target_desc.  */
 333 target_desc_up allocate_target_description (void);
 334
 335 /* Set TARGET_DESC's architecture by NAME.  */
 336 void set_tdesc_architecture (target_desc *target_desc,
 337                              const char *name);
 338
 339 /* Return the architecture associated with this target description as a string,
 340    or NULL if no architecture was specified.  */
 341 const char *tdesc_architecture_name (const struct target_desc *target_desc);
 342
 343 /* Set TARGET_DESC's osabi to OSABI.  */
 344 void set_tdesc_osabi (target_desc *target_desc, enum gdb_osabi osabi);
 345
 346 /* Return the osabi associated with this target description as a string,
 347    or NULL if no osabi was specified.  */
 348 const char *tdesc_osabi_name (const struct target_desc *target_desc);
 349
 350 /* Return the type associated with ID in the context of FEATURE, or
 351    NULL if none.  */
 352 struct tdesc_type *tdesc_named_type (const struct tdesc_feature *feature,
 353                                      const char *id);
 354
 355 /* Return the created feature named NAME in target description TDESC.  */
 356 struct tdesc_feature *tdesc_create_feature (struct target_desc *tdesc,
 357                                             const char *name);
 358
 359 /* Return the created vector tdesc_type named NAME in FEATURE.  */
 360 struct tdesc_type *tdesc_create_vector (struct tdesc_feature *feature,
 361                                         const char *name,
 362                                         struct tdesc_type *field_type,
 363                                         int count);
 364
 365 /* Return the created struct tdesc_type named NAME in FEATURE.  */
 366 tdesc_type_with_fields *tdesc_create_struct (struct tdesc_feature *feature,
 367                                              const char *name);
 368
 369 /* Return the created union tdesc_type named NAME in FEATURE.  */
 370 tdesc_type_with_fields *tdesc_create_union (struct tdesc_feature *feature,
 371                                             const char *name);
 372
 373 /* Return the created flags tdesc_type named NAME in FEATURE.  */
 374 tdesc_type_with_fields *tdesc_create_flags (struct tdesc_feature *feature,
 375                                             const char *name,
 376                                             int size);
 377
 378 /* Return the created enum tdesc_type named NAME in FEATURE.  */
 379 tdesc_type_with_fields *tdesc_create_enum (struct tdesc_feature *feature,
 380                                            const char *name,
 381                                            int size);
 382
 383 /* Add a new field to TYPE.  FIELD_NAME is its name, and FIELD_TYPE is
 384    its type.  */
 385 void tdesc_add_field (tdesc_type_with_fields *type, const char *field_name,
 386                       struct tdesc_type *field_type);
 387
 388 /* Add a new bitfield to TYPE, with range START to END.  FIELD_NAME is its name,
 389    and FIELD_TYPE is its type.  */
 390 void tdesc_add_typed_bitfield (tdesc_type_with_fields *type,
 391                                const char *field_name,
 392                                int start, int end,
 393                                struct tdesc_type *field_type);
 394
 395 /* Set the total length of TYPE.  Structs which contain bitfields may
 396    omit the reserved bits, so the end of the last field may not
 397    suffice.  */
 398 void tdesc_set_struct_size (tdesc_type_with_fields *type, int size);
 399
 400 /* Add a new untyped bitfield to TYPE.
 401    Untyped bitfields become either uint32 or uint64 depending on the size
 402    of the underlying type.  */
 403 void tdesc_add_bitfield (tdesc_type_with_fields *type, const char *field_name,
 404                          int start, int end);
 405
 406 /* A flag is just a typed(bool) single-bit bitfield.
 407    This function is kept to minimize changes in generated files.  */
 408 void tdesc_add_flag (tdesc_type_with_fields *type, int start,
 409                      const char *flag_name);
 410
 411 /* Add field with VALUE and NAME to the enum TYPE.  */
 412 void tdesc_add_enum_value (tdesc_type_with_fields *type, int value,
 413                            const char *name);
 414
 415 /* Create a register in feature FEATURE.  */
 416 void tdesc_create_reg (struct tdesc_feature *feature, const char *name,
 417                        int regnum, int save_restore, const char *group,
 418                        int bitsize, const char *type);
 419
 420 /* Return the tdesc in string XML format.  */
 421
 422 const char *tdesc_get_features_xml (const target_desc *tdesc);
 423
 424 /* Print target description as xml.  */
 425
 426 class print_xml_feature : public tdesc_element_visitor
 427 {
 428 public:
 429   print_xml_feature (std::string *buffer_)
 430     : m_buffer (buffer_),
 431       m_depth (0)
 432   {}
 433
 434   void visit_pre (const target_desc *e) override;
 435   void visit_post (const target_desc *e) override;
 436   void visit_pre (const tdesc_feature *e) override;
 437   void visit_post (const tdesc_feature *e) override;
 438   void visit (const tdesc_type_builtin *type) override;
 439   void visit (const tdesc_type_vector *type) override;
 440   void visit (const tdesc_type_with_fields *type) override;
 441   void visit (const tdesc_reg *reg) override;
 442
 443 private:
 444
 445   /* Called with a positive value of ADJUST when we move inside an element,
 446      for example inside <target>, and with a negative value when we leave
 447      the element.  In this class this function does nothing, but a
 448      sub-class can override this to track the current level of nesting.  */
 449   void indent (int adjust)
 450   {
 451     m_depth += (adjust * 2);
 452   }
 453
 454   /* Functions to add lines to the output buffer M_BUFFER.  Each of these
 455      functions appends a newline, so don't include one in the strings being
 456      passed.  */
 457   void add_line (const std::string &str);
 458   void add_line (const char *fmt, ...) ATTRIBUTE_PRINTF (2, 3);
 459
 460   /* The buffer we are writing too.  */
 461   std::string *m_buffer;
 462
 463   /* The current indentation depth.  */
 464   int m_depth;
 465 };
 466
 467 #endif /* COMMON_TDESC_H */