gdb/regcache.h

   1 /* Cache and manage the values of registers for GDB, the GNU debugger.
   2
   3    Copyright (C) 1986-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 #ifndef GDB_REGCACHE_H
  21 #define GDB_REGCACHE_H
  22
  23 #include "gdbsupport/array-view.h"
  24 #include "gdbsupport/common-regcache.h"
  25 #include "gdbsupport/function-view.h"
  26 #include "gdbsupport/traits.h"
  27
  28 struct regcache;
  29 struct regset;
  30 struct gdbarch;
  31 class thread_info;
  32 struct process_stratum_target;
  33 struct inferior;
  34 class ui_out;
  35
  36 extern struct regcache *get_thread_regcache (process_stratum_target *target,
  37                                              ptid_t ptid);
  38
  39 /* Get the regcache of THREAD.  */
  40 extern struct regcache *get_thread_regcache (thread_info *thread);
  41
  42 extern regcache *get_thread_arch_regcache (inferior *inf_for_target_calls,
  43                                            ptid_t ptid, gdbarch *arch);
  44
  45 extern enum register_status
  46   regcache_raw_read_signed (struct regcache *regcache,
  47                             int regnum, LONGEST *val);
  48
  49 extern void regcache_raw_write_signed (struct regcache *regcache,
  50                                        int regnum, LONGEST val);
  51 extern void regcache_raw_write_unsigned (struct regcache *regcache,
  52                                          int regnum, ULONGEST val);
  53
  54 /* Return the register's value in signed or throw if it's not
  55    available.  */
  56
  57 extern LONGEST regcache_raw_get_signed (struct regcache *regcache,
  58                                         int regnum);
  59
  60 /* Read a register as a signed/unsigned quantity.  */
  61 extern enum register_status
  62   regcache_cooked_read_signed (struct regcache *regcache,
  63                                int regnum, LONGEST *val);
  64 extern enum register_status
  65   regcache_cooked_read_unsigned (struct regcache *regcache,
  66                                  int regnum, ULONGEST *val);
  67 extern void regcache_cooked_write_signed (struct regcache *regcache,
  68                                           int regnum, LONGEST val);
  69 extern void regcache_cooked_write_unsigned (struct regcache *regcache,
  70                                             int regnum, ULONGEST val);
  71
  72 /* Special routines to read/write the PC.  */
  73
  74 /* For regcache_read_pc see gdbsupport/common-regcache.h.  */
  75 extern void regcache_write_pc (struct regcache *regcache, CORE_ADDR pc);
  76
  77 /* Mapping between register numbers and offsets in a buffer, for use
  78    in the '*regset' functions below and with traditional frame caches.
  79    In an array of 'regcache_map_entry' each element is interpreted
  80    like follows:
  81
  82    - If 'regno' is a register number: Map register 'regno' to the
  83      current offset (starting with 0) and increase the current offset
  84      by 'size' (or the register's size, if 'size' is zero).  Repeat
  85      this with consecutive register numbers up to 'regno+count-1'.
  86
  87      For each described register, if 'size' is larger than the
  88      register's size, the register's value is assumed to be stored in
  89      the first N (where N is the register size) bytes at the current
  90      offset.  The remaining 'size' - N bytes are filled with zeroes by
  91      'regcache_collect_regset' and ignored by other consumers.
  92
  93      If 'size' is smaller than the register's size, only the first
  94      'size' bytes of a register's value are assumed to be stored at
  95      the current offset.  'regcache_collect_regset' copies the first
  96      'size' bytes of a register's value to the output buffer.
  97      'regcache_supply_regset' copies the bytes from the input buffer
  98      into the first 'size' bytes of the register's value leaving the
  99      remaining bytes of the register's value unchanged.  Frame caches
 100      read the 'size' bytes from the stack frame and zero extend them
 101      to generate the register's value.
 102
 103    - If 'regno' is REGCACHE_MAP_SKIP: Add 'count*size' to the current
 104      offset.
 105
 106    - If count=0: End of the map.  */
 107
 108 struct regcache_map_entry
 109 {
 110   int count;
 111   int regno;
 112   int size;
 113 };
 114
 115 /* Special value for the 'regno' field in the struct above.  */
 116
 117 enum
 118   {
 119     REGCACHE_MAP_SKIP = -1,
 120   };
 121
 122 /* Calculate and return the total size of all the registers in a
 123    regcache_map_entry.  */
 124
 125 static inline int
 126 regcache_map_entry_size (const struct regcache_map_entry *map)
 127 {
 128   int size = 0;
 129   for (int i = 0; map[i].count != 0; i++)
 130     size += (map[i].count * map[i].size);
 131   return size;
 132 }
 133
 134 /* Transfer a set of registers (as described by REGSET) between
 135    REGCACHE and BUF.  If REGNUM == -1, transfer all registers
 136    belonging to the regset, otherwise just the register numbered
 137    REGNUM.  The REGSET's 'regmap' field must point to an array of
 138    'struct regcache_map_entry'.
 139
 140    These functions are suitable for the 'regset_supply' and
 141    'regset_collect' fields in a regset structure.  */
 142
 143 extern void regcache_supply_regset (const struct regset *regset,
 144                                     struct regcache *regcache,
 145                                     int regnum, const void *buf,
 146                                     size_t size);
 147 extern void regcache_collect_regset (const struct regset *regset,
 148                                      const struct regcache *regcache,
 149                                      int regnum, void *buf, size_t size);
 150
 151
 152 /* Return true if a set of registers contains the value of the
 153    register numbered REGNUM.  The size of the set of registers is
 154    given in SIZE, and the layout of the set of registers is described
 155    by MAP.  */
 156
 157 extern bool regcache_map_supplies (const struct regcache_map_entry *map,
 158                                    int regnum, struct gdbarch *gdbarch,
 159                                    size_t size);
 160
 161 /* The type of a register.  This function is slightly more efficient
 162    then its gdbarch vector counterpart since it returns a precomputed
 163    value stored in a table.  */
 164
 165 extern struct type *register_type (struct gdbarch *gdbarch, int regnum);
 166
 167
 168 /* Return the size of register REGNUM.  All registers should have only
 169    one size.  */
 170
 171 extern int register_size (struct gdbarch *gdbarch, int regnum);
 172
 173 using register_read_ftype
 174   = gdb::function_view<register_status (int, gdb::array_view<gdb_byte>)>;
 175
 176 /* A (register_number, register_value) pair.  */
 177
 178 struct cached_reg_t
 179 {
 180   int num;
 181   gdb::byte_vector data;
 182 };
 183
 184 /* Buffer of registers.  */
 185
 186 class reg_buffer : public reg_buffer_common
 187 {
 188 public:
 189   reg_buffer (gdbarch *gdbarch, bool has_pseudo);
 190
 191   DISABLE_COPY_AND_ASSIGN (reg_buffer);
 192
 193   /* Return regcache's architecture.  */
 194   gdbarch *arch () const;
 195
 196   /* See gdbsupport/common-regcache.h.  */
 197   enum register_status get_register_status (int regnum) const override;
 198
 199   /* See gdbsupport/common-regcache.h.  */
 200   void raw_collect (int regnum, gdb::array_view<gdb_byte> dst) const override;
 201
 202   /* Deprecated overload of the above.  */
 203   void raw_collect (int regnum, void *dst) const;
 204
 205   /* Collect register REGNUM from REGCACHE.  Store collected value as an integer
 206      at address ADDR, in target endian, with length ADDR_LEN and sign IS_SIGNED.
 207      If ADDR_LEN is greater than the register size, then the integer will be
 208      sign or zero extended.  If ADDR_LEN is smaller than the register size, then
 209      the most significant bytes of the integer will be truncated.  */
 210   void raw_collect_integer (int regnum, gdb_byte *addr, int addr_len,
 211                             bool is_signed) const;
 212
 213   /* Collect part of register REGNUM from this register buffer.  Start at OFFSET
 214      in register.  The size is given by the size of DST.  */
 215   void raw_collect_part (int regnum, int offset,
 216                          gdb::array_view<gdb_byte> dst) const;
 217
 218   /* Deprecated overload of the above.  */
 219   void raw_collect_part (int regnum, int offset, int len, gdb_byte *dst) const
 220   { raw_collect_part (regnum, offset, gdb::make_array_view (dst, len)); }
 221
 222   /* See gdbsupport/common-regcache.h.  */
 223   void raw_supply (int regnum, gdb::array_view<const gdb_byte> src) override;
 224
 225   /* Deprecated overload of the above.  */
 226   void raw_supply (int regnum, const void *src);
 227
 228   void raw_supply (int regnum, const reg_buffer &src)
 229   { raw_supply (regnum, src.register_buffer (regnum)); }
 230
 231   /* Supply register REGNUM to REGCACHE.  Value to supply is an integer stored
 232      at address ADDR, in target endian, with length ADDR_LEN and sign IS_SIGNED.
 233      If the register size is greater than ADDR_LEN, then the integer will be
 234      sign or zero extended.  If the register size is smaller than the integer,
 235      then the most significant bytes of the integer will be truncated.  */
 236   void raw_supply_integer (int regnum, const gdb_byte *addr, int addr_len,
 237                            bool is_signed);
 238
 239   /* Supply register REGNUM with zeroed value to REGCACHE.  This is not the same
 240      as calling raw_supply with NULL (which will set the state to
 241      unavailable).  */
 242   void raw_supply_zeroed (int regnum);
 243
 244   /* See gdbsupport/common-regcache.h.  */
 245   void raw_supply_part_zeroed (int regnum, int offset, size_t size) override;
 246
 247   /* Supply part of register REGNUM to this register buffer.  Start at OFFSET in
 248      the register.  The size is given by the size of SRC.  The rest of the
 249      register left untouched.  */
 250   void raw_supply_part (int regnum, int offset,
 251                         gdb::array_view<const gdb_byte> src);
 252
 253   void invalidate (int regnum);
 254
 255   virtual ~reg_buffer () = default;
 256
 257   /* See gdbsupport/common-regcache.h.  */
 258   bool raw_compare (int regnum, const void *buf, int offset) const override;
 259
 260   /* See gdbsupport/common-regcache.h.  */
 261   int register_size (int regnum) const override;
 262
 263 protected:
 264   /* Assert on the range of REGNUM.  */
 265   void assert_regnum (int regnum) const;
 266
 267   int num_raw_registers () const;
 268
 269   /* Return a view on register REGNUM's buffer cache.  */
 270   template <typename ElemType>
 271   gdb::array_view<ElemType> register_buffer (int regnum) const;
 272   gdb::array_view<const gdb_byte> register_buffer (int regnum) const;
 273   gdb::array_view<gdb_byte> register_buffer (int regnum);
 274
 275   /* Save a register cache.  The set of registers saved into the
 276      regcache determined by the save_reggroup.  COOKED_READ returns
 277      zero iff the register's value can't be returned.  */
 278   void save (register_read_ftype cooked_read);
 279
 280   struct regcache_descr *m_descr;
 281
 282   bool m_has_pseudo;
 283   /* The register buffers.  */
 284   std::unique_ptr<gdb_byte[]> m_registers;
 285   /* Register cache status.  */
 286   std::unique_ptr<register_status[]> m_register_status;
 287
 288   friend class regcache;
 289   friend class detached_regcache;
 290 };
 291
 292 /* An abstract class which only has methods doing read.  */
 293
 294 class readable_regcache : public reg_buffer
 295 {
 296 public:
 297   readable_regcache (gdbarch *gdbarch, bool has_pseudo)
 298     : reg_buffer (gdbarch, has_pseudo)
 299   {}
 300
 301   /* Transfer a raw register [0..NUM_REGS) from core-gdb to this regcache,
 302      return its value in *BUF and return its availability status.  */
 303   register_status raw_read (int regnum, gdb::array_view<gdb_byte> dst);
 304
 305   /* Deprecated overload of the above.  */
 306   register_status raw_read (int regnum, gdb_byte *dst);
 307
 308   template<typename T, typename = RequireLongest<T>>
 309   register_status raw_read (int regnum, T *val);
 310
 311   /* Partial transfer of raw registers.  Return the status of the register.  */
 312   register_status raw_read_part (int regnum, int offset,
 313                                  gdb::array_view<gdb_byte> dst);
 314
 315   /* Deprecated overload of the above.  */
 316   register_status raw_read_part (int regnum, int offset, int len,
 317                                  gdb_byte *dst)
 318   { return raw_read_part (regnum, offset, gdb::make_array_view (dst, len)); }
 319
 320   /* Make certain that the register REGNUM is up-to-date.  */
 321   virtual void raw_update (int regnum) = 0;
 322
 323   /* Transfer a raw register [0..NUM_REGS+NUM_PSEUDO_REGS) from core-gdb to
 324      this regcache, return its value in DST and return its availability status.  */
 325   register_status cooked_read (int regnum, gdb::array_view<gdb_byte> dst);
 326   register_status cooked_read (int regnum, gdb_byte *dst);
 327
 328   template<typename T, typename = RequireLongest<T>>
 329   register_status cooked_read (int regnum, T *val);
 330
 331   /* Partial transfer of a cooked register.  */
 332   register_status cooked_read_part (int regnum, int offset,
 333                                     gdb::array_view<gdb_byte> dst);
 334
 335   /* Deprecated overload of the above.  */
 336   register_status cooked_read_part (int regnum, int offset, int len, gdb_byte *src)
 337   { return cooked_read_part (regnum, offset, gdb::make_array_view (src, len)); }
 338
 339   /* Read register REGNUM from the regcache and return a new value.  This
 340      will call mark_value_bytes_unavailable as appropriate.  */
 341   struct value *cooked_read_value (int regnum);
 342
 343 protected:
 344
 345   /* Perform a partial register transfer using a read, modify, write
 346      operation.  Will fail if register is currently invalid.  */
 347   register_status read_part (int regnum, int offset,
 348                              gdb::array_view<gdb_byte> dst, bool is_raw);
 349 };
 350
 351 /* Buffer of registers, can be read and written.  */
 352
 353 class detached_regcache : public readable_regcache
 354 {
 355 public:
 356   detached_regcache (gdbarch *gdbarch, bool has_pseudo)
 357     : readable_regcache (gdbarch, has_pseudo)
 358   {}
 359
 360   void raw_update (int regnum) override
 361   {}
 362
 363   DISABLE_COPY_AND_ASSIGN (detached_regcache);
 364 };
 365
 366 class readonly_detached_regcache;
 367
 368 /* The register cache for storing raw register values.  */
 369
 370 class regcache : public detached_regcache
 371 {
 372 public:
 373   DISABLE_COPY_AND_ASSIGN (regcache);
 374
 375   /* Restore 'this' regcache.  The set of registers restored into
 376      the regcache determined by the restore_reggroup.
 377      Writes to regcache will go through to the target.  SRC is a
 378      read-only register cache.  */
 379   void restore (readonly_detached_regcache *src);
 380
 381   /* Update the value of raw register REGNUM (in the range [0..NUM_REGS)) and
 382      transfer its value to core-gdb.  */
 383
 384   void raw_write (int regnum, gdb::array_view<const gdb_byte> src);
 385
 386   /* Deprecated overload of the above.  */
 387   void raw_write (int regnum, const gdb_byte *src);
 388
 389   template<typename T, typename = RequireLongest<T>>
 390   void raw_write (int regnum, T val);
 391
 392   /* Transfer of pseudo-registers.  */
 393   void cooked_write (int regnum, gdb::array_view<const gdb_byte> src);
 394
 395   /* Deprecated overload of the above.  */
 396   void cooked_write (int regnum, const gdb_byte *src);
 397
 398   template<typename T, typename = RequireLongest<T>>
 399   void cooked_write (int regnum, T val);
 400
 401   void raw_update (int regnum) override;
 402
 403   /* Partial transfer of raw registers.  Perform read, modify, write style
 404      operations.  */
 405   void raw_write_part (int regnum, int offset,
 406                        gdb::array_view<const gdb_byte> src);
 407
 408   /* Deprecated overload of the above.  */
 409   void raw_write_part (int regnum, int offset, int len, const gdb_byte *src)
 410   { raw_write_part (regnum, offset, gdb::make_array_view (src, len)); }
 411
 412   /* Partial transfer of a cooked register.  Perform read, modify, write style
 413      operations.  */
 414   void cooked_write_part (int regnum, int offset,
 415                           gdb::array_view<const gdb_byte> src);
 416
 417   /* Deprecated overload of the above.  */
 418   void cooked_write_part (int regnum, int offset, int len, const gdb_byte *src)
 419   { cooked_write_part (regnum, offset, gdb::make_array_view (src, len)); }
 420
 421   /* Transfer a set of registers (as described by REGSET) between
 422      REGCACHE and BUF.  If REGNUM == -1, transfer all registers
 423      belonging to the regset, otherwise just the register numbered
 424      REGNUM.  The REGSET's 'regmap' field must point to an array of
 425      'struct regcache_map_entry'.  The valid register numbers in each
 426      entry in 'struct regcache_map_entry' are offset by REGBASE.  */
 427
 428   void supply_regset (const struct regset *regset, int regbase,
 429                       int regnum, const void *buf, size_t size);
 430
 431   void collect_regset (const struct regset *regset, int regbase, int regnum,
 432                        void *buf, size_t size) const;
 433
 434   /* Same as the above, but with REGBASE == 0.  */
 435
 436   void supply_regset (const struct regset *regset,
 437                       int regnum, const void *buf, size_t size)
 438   {
 439     supply_regset (regset, 0, regnum, buf, size);
 440   }
 441
 442   void collect_regset (const struct regset *regset, int regnum,
 443                        void *buf, size_t size) const
 444   {
 445     collect_regset (regset, 0, regnum, buf, size);
 446   }
 447
 448   /* Return REGCACHE's ptid.  */
 449
 450   ptid_t ptid () const
 451   {
 452     gdb_assert (m_ptid != minus_one_ptid);
 453
 454     return m_ptid;
 455   }
 456
 457   void set_ptid (const ptid_t ptid)
 458   {
 459     this->m_ptid = ptid;
 460   }
 461
 462   /* Return a string with the contents of a register, suitable for debug output.  */
 463   std::string register_debug_string (int regno);
 464
 465 protected:
 466   regcache (inferior *inf_for_target_calls, gdbarch *gdbarch);
 467
 468 private:
 469
 470   /* Helper function for transfer_regset.  Copies across a single register.  */
 471   void transfer_regset_register (struct regcache *out_regcache, int regnum,
 472                                  const gdb_byte *in_buf, gdb_byte *out_buf,
 473                                  int slot_size, int offs) const;
 474
 475   /* Transfer a single or all registers belonging to a certain register
 476      set to or from a buffer.  This is the main worker function for
 477      regcache_supply_regset and regcache_collect_regset.  */
 478   void transfer_regset (const struct regset *regset, int regbase,
 479                         struct regcache *out_regcache,
 480                         int regnum, const gdb_byte *in_buf,
 481                         gdb_byte *out_buf, size_t size) const;
 482
 483   /* Perform a partial register transfer using a read, modify, write
 484      operation.  */
 485   register_status write_part (int regnum, int offset,
 486                               gdb::array_view<const gdb_byte> src,
 487                               bool is_raw);
 488
 489   /* The inferior to switch to, to make target calls.
 490
 491      This may not be the inferior of thread M_PTID.  For instance, this
 492      regcache might be for a fork child we are about to detach, so there will
 493      never be an inferior for that thread / process.  Nevertheless, we need to
 494      be able to switch to the target stack that can handle register reads /
 495      writes for this regcache, and that's what this inferior is for.  */
 496   inferior *m_inf_for_target_calls;
 497
 498   /* If this is a read-write cache, which thread's registers is
 499      it connected to?  */
 500   ptid_t m_ptid;
 501
 502   friend regcache *get_thread_arch_regcache (inferior *inf_for_target_calls,
 503                                              ptid_t ptid, gdbarch *gdbarch);
 504 };
 505
 506 using regcache_up = std::unique_ptr<regcache>;
 507
 508 class readonly_detached_regcache : public readable_regcache
 509 {
 510 public:
 511   readonly_detached_regcache (regcache &src);
 512
 513   /* Create a readonly regcache by getting contents from COOKED_READ.  */
 514
 515   readonly_detached_regcache (gdbarch *gdbarch, register_read_ftype cooked_read)
 516     : readable_regcache (gdbarch, true)
 517   {
 518     save (cooked_read);
 519   }
 520
 521   DISABLE_COPY_AND_ASSIGN (readonly_detached_regcache);
 522
 523   void raw_update (int regnum) override
 524   {}
 525 };
 526
 527 extern void registers_changed (void);
 528 extern void registers_changed_ptid (process_stratum_target *target,
 529                                     ptid_t ptid);
 530
 531 /* Indicate that registers of THREAD may have changed, so invalidate
 532    the cache.  */
 533 extern void registers_changed_thread (thread_info *thread);
 534
 535 /* An abstract base class for register dump.  */
 536
 537 class register_dump
 538 {
 539 public:
 540   void dump (ui_out *out, const char *name);
 541   virtual ~register_dump () = default;
 542
 543 protected:
 544   register_dump (gdbarch *arch)
 545     : m_gdbarch (arch)
 546   {}
 547
 548   /* Number of additional table headers.  */
 549   virtual int num_additional_headers () = 0;
 550
 551   /* Add the additional headers to OUT.  */
 552   virtual void additional_headers (ui_out *out) = 0;
 553
 554   /* Dump the register REGNUM contents.  */
 555   virtual void dump_reg (ui_out *out, int regnum) = 0;
 556
 557   gdbarch *m_gdbarch;
 558 };
 559
 560 #endif /* GDB_REGCACHE_H */