// Copyright (c) Meta Platforms, Inc. and affiliates. // SPDX-License-Identifier: LGPL-2.1-or-later /** * @file * * Register state. * * See @ref RegisterState. */ #ifndef DRGN_REGISTER_STATE_H #define DRGN_REGISTER_STATE_H #include #include #include #include "cfi.h" #include "drgn_internal.h" #include "platform.h" #include "program.h" #include "serialize.h" #include "util.h" /** * @ingroup Internals * * @defgroup RegisterState Register state * * Buffer of processor register values. * * This defines @ref drgn_register_state for storing the values of processor * registers. * * Several macros defined here take a register identifier as defined in an * architecture definition file. These are intended for use in the corresponding * architecture support file. These macros also have function equivalents (with * names ending in `_impl`) that take the register number, offset, and size * instead. * * @{ */ /** * State of processor registers (e.g., in a stack frame), including the program * counter and Canonical Frame Address (some of which may not be known). */ struct drgn_register_state { /** * Cached @ref drgn_module that contains the program counter. * * This is `NULL` if the program counter is not known or if the * containing module could not be found. */ struct drgn_module *module; /** Total size of registers allocated in @ref drgn_register_state::buf. */ uint32_t regs_size; /** Number of registers allocated in @ref drgn_register_state::buf. */ uint16_t num_regs; /** Whether this frame was interrupted (e.g., by a signal). */ bool interrupted; /** Program counter. Access with @ref drgn_register_state_get_pc(). */ uint64_t _pc; /** * Canonical Frame Address. Access with @ref * drgn_register_state_get_cfa(). */ uint64_t _cfa; /** * Buffer of register values followed by bitset indicating which * register values are known. * * The layout of the register values is architecture-specific and * defined by @ref DRGN_ARCH_REGISTER_LAYOUT. * * Bit 0 of the bitset is whether the PC is known, bit 1 is whether the * CFA is known, and the remaining @ref drgn_register_state::num_regs * bits are whether each register is known. * * Registers beyond @ref drgn_register_state::regs_size ""/@ref * drgn_register_state::num_regs are not allocated here and are assumed * to be unknown. */ unsigned char buf[]; }; /** * Return the internal register number of a register. * * @param[in] id Register identifier. */ #define DRGN_REGISTER_NUMBER(id) DRGN_REGISTER_NUMBER__##id /** * Return the offset of a register in the register buffer. * * @param[in] id Register identifier. */ #define DRGN_REGISTER_OFFSET(id) offsetof(struct drgn_arch_register_layout, id) /** * Return the size of a register in bytes. * * @param[in] id Register identifier. */ #define DRGN_REGISTER_SIZE(id) sizeof(((struct drgn_arch_register_layout *)0)->id) /** * Return one past the last byte of a register in the register buffer. * * @param[in] id Register identifier. */ #define DRGN_REGISTER_END(id) (DRGN_REGISTER_OFFSET(id) + DRGN_REGISTER_SIZE(id)) struct drgn_register_state *drgn_register_state_create_impl(uint32_t regs_size, uint16_t num_regs, bool interrupted); /** * Create a @ref drgn_register_state large enough to store up to and including a * given register. * * @param[in] last_reg Identifier of last register to allocate. * @param[in] interrupted @ref drgn_register_state::interrupted * @return New register state on success, @c NULL on failure to allocate memory. */ #define drgn_register_state_create(last_reg, interrupted) \ drgn_register_state_create_impl(DRGN_REGISTER_END(last_reg), \ DRGN_REGISTER_NUMBER(last_reg) + 1, \ interrupted) /** * Create a copy of a @ref drgn_register_state. * * @return New register state on success, @c NULL on failure to allocate memory. */ struct drgn_register_state * drgn_register_state_dup(const struct drgn_register_state *regs); /** Free a @ref drgn_register_state. */ static inline void drgn_register_state_destroy(struct drgn_register_state *regs) { free(regs); } /** * Get whether the value of a register is known in a @ref drgn_register_state. * * @param[in] regno Register number to check. May be @c * DRGN_REGISTER_NUMBER_UNKNOWN, in which case this always returns @c false. */ bool drgn_register_state_has_register(const struct drgn_register_state *regs, drgn_register_number regno) __attribute__((__pure__)); /** * Mark a register as known in a @ref drgn_register_state. * * @param[in] regno Register number to mark as known. Must be less than @ref * drgn_register_state::num_regs. */ void drgn_register_state_set_has_register(struct drgn_register_state *regs, drgn_register_number regno); /** * Mark a range of adjacent registers as known in a @ref drgn_register_state. * * @param[in] first_regno First register number to mark as known (inclusive). * Must be less than or equal to @p last_regno. * @param[in] last_regno Last register number to mark as known (inclusive). Must * be less than @ref drgn_register_state::num_regs. */ void drgn_register_state_set_has_register_range(struct drgn_register_state *regs, drgn_register_number first_regno, drgn_register_number last_regno); /** * Mark a register as unknown in a @ref drgn_register_state. * * @param[in] regno Register number to mark as unknown. */ void drgn_register_state_unset_has_register(struct drgn_register_state *regs, drgn_register_number regno); /** A `uint64_t` which may or may not be present. */ struct optional_uint64 { uint64_t value; bool has_value; }; /** Get the value of the program counter in a @ref drgn_register_state. */ struct optional_uint64 drgn_register_state_get_pc(const struct drgn_register_state *regs) __attribute__((__pure__)); /** * Set the value of the program counter in a @ref drgn_register_state and mark * it as known. */ void drgn_register_state_set_pc(struct drgn_program *prog, struct drgn_register_state *regs, uint64_t pc); static inline void drgn_register_state_set_pc_from_register_impl(struct drgn_program *prog, struct drgn_register_state *regs, drgn_register_number regno, size_t reg_offset, size_t reg_size) { assert(drgn_register_state_has_register(regs, regno)); uint64_t pc; copy_lsbytes(&pc, sizeof(pc), HOST_LITTLE_ENDIAN, ®s->buf[reg_offset], reg_size, drgn_platform_is_little_endian(&prog->platform)); drgn_register_state_set_pc(prog, regs, pc); } /** * Set the value of the program counter in a @ref drgn_register_state from the * value of a register and mark it as known. * * @param[in] reg Identifier of register to set from. Value must be known. */ #define drgn_register_state_set_pc_from_register(prog, regs, reg) \ drgn_register_state_set_pc_from_register_impl(prog, regs, \ DRGN_REGISTER_NUMBER(reg),\ DRGN_REGISTER_OFFSET(reg),\ DRGN_REGISTER_SIZE(reg)) /** * Get the value of the Canonical Frame Address in a @ref drgn_register_state. */ struct optional_uint64 drgn_register_state_get_cfa(const struct drgn_register_state *regs) __attribute__((__pure__)); /** * Set the value of the Canonical Frame Address in a @ref drgn_register_state * and mark it as known. */ void drgn_register_state_set_cfa(struct drgn_program *prog, struct drgn_register_state *regs, uint64_t cfa); struct optional_uint64 drgn_register_state_get_u64_impl(struct drgn_program *prog, struct drgn_register_state *regs, drgn_register_number regno, size_t reg_offset, size_t reg_size) __attribute__((__pure__)); /** * Get the least significant 64 bits of a register in a @ref * drgn_register_state. * * @param[in] reg Identifier of register to get. */ #define drgn_register_state_get_u64(prog, regs, reg) \ drgn_register_state_get_u64_impl(prog, regs, \ DRGN_REGISTER_NUMBER(reg), \ DRGN_REGISTER_OFFSET(reg), \ DRGN_REGISTER_SIZE(reg)) static inline void drgn_register_state_set_from_buffer_impl(struct drgn_register_state *regs, drgn_register_number regno, size_t reg_offset, size_t reg_size, const void *buf) { memcpy(®s->buf[reg_offset], buf, reg_size); drgn_register_state_set_has_register(regs, regno); } /** * Set the value of a register in a @ref drgn_register_state from a buffer and * mark it as known. * * The buffer must be at least as large as the register. * * @param[in] reg Identifier of register to set. Number must be less than @ref * drgn_register_state::num_regs. */ #define drgn_register_state_set_from_buffer(regs, reg, buf) \ drgn_register_state_set_from_buffer_impl(regs, \ DRGN_REGISTER_NUMBER(reg), \ DRGN_REGISTER_OFFSET(reg), \ DRGN_REGISTER_SIZE(reg), \ buf) static inline void drgn_register_state_set_range_from_buffer_impl(struct drgn_register_state *regs, drgn_register_number first_regno, drgn_register_number last_regno, size_t first_reg_offset, size_t last_reg_end, const void *buf) { memcpy(®s->buf[first_reg_offset], buf, last_reg_end - first_reg_offset); drgn_register_state_set_has_register_range(regs, first_regno, last_regno); } /** * Set the values of a range of adjacent registers in a @ref drgn_register_state * from a buffer and mark them as known. * * @param[in] first_reg Identifier of first register to set (inclusive). Number * must be less than or equal to number of @p last_reg. * @param[in] last_reg Identifier of last register to set (inclusive). Number * must be less than @ref drgn_register_state::num_regs. */ #define drgn_register_state_set_range_from_buffer(regs, first_reg, last_reg, buf) \ drgn_register_state_set_range_from_buffer_impl(regs, \ DRGN_REGISTER_NUMBER(first_reg), \ DRGN_REGISTER_NUMBER(last_reg), \ DRGN_REGISTER_OFFSET(first_reg), \ DRGN_REGISTER_END(last_reg), \ buf) static inline void drgn_register_state_set_from_u64_impl(struct drgn_program *prog, struct drgn_register_state *regs, drgn_register_number regno, size_t reg_offset, size_t reg_size, uint64_t value) { copy_lsbytes(®s->buf[reg_offset], reg_size, drgn_platform_is_little_endian(&prog->platform), &value, sizeof(value), HOST_LITTLE_ENDIAN); drgn_register_state_set_has_register(regs, regno); } /** * Set the value of a register in a @ref drgn_register_state from a `uint64_t` * and mark it as known. * * If the register is smaller than 8 bytes, then the value is truncated to the * least significant bytes. If it is larger, then the value is zero-extended. * * @param[in] reg Identifier of register to set. Number must be less than @ref * drgn_register_state::num_regs. */ #define drgn_register_state_set_from_u64(prog, regs, reg, value) \ drgn_register_state_set_from_u64_impl(prog, regs, \ DRGN_REGISTER_NUMBER(reg), \ DRGN_REGISTER_OFFSET(reg), \ DRGN_REGISTER_SIZE(reg), value) /** @} */ #endif /* DRGN_REGISTER_STATE_H */