[PATCH 34/43] Comments cleanup between expr.h and expr.c

Zoran Zaric via Gdb-patches
2021-03-01T14:47:57Z

This is just a cosmetic cleanup of the expr.h and expr.c documentation.

gdb/ChangeLog:

* dwarf2/expr.c: Comments cleanup.
* dwarf2/expr.h: Comments cleanup.
---
gdb/dwarf2/expr.c | 42 ++++++++++++++++------------------------
gdb/dwarf2/expr.h | 49 +++++++++++++++++++++++++++++++++++++++++++++--
2 files changed, 64 insertions(+), 27 deletions(-)

diff --git a/gdb/dwarf2/expr.c b/gdb/dwarf2/expr.c
index e45a7755ec5..aa28d632442 100644
--- a/gdb/dwarf2/expr.c
+++ b/gdb/dwarf2/expr.c
@@ -2241,7 +2241,7 @@ dwarf_expr_context::dwarf_expr_context (dwarf2_per_objfile *per_objfile,
{
}

-/* Push ENTRY onto the stack. */
+/* See expr.h. */

void
dwarf_expr_context::push (std::shared_ptr<dwarf_entry> entry)
@@ -2249,7 +2249,7 @@ dwarf_expr_context::push (std::shared_ptr<dwarf_entry> entry)
stack.emplace_back (entry);
}

-/* Push ADDR onto the stack. */
+/* See expr.h. */

void
dwarf_expr_context::push_address (CORE_ADDR addr, bool in_stack_memory)
@@ -2259,7 +2259,7 @@ dwarf_expr_context::push_address (CORE_ADDR addr, bool in_stack_memory)
}

-/* Pop the top item off of the stack. */
+/* See expr.h. */

void
dwarf_expr_context::pop ()
@@ -2270,7 +2270,7 @@ dwarf_expr_context::pop ()
stack.pop_back ();
}

-/* Retrieve the N'th item on the stack. */
+/* See expr.h. */

std::shared_ptr<dwarf_entry>
dwarf_expr_context::fetch (int n)
@@ -2506,7 +2506,7 @@ get_signed_type (struct gdbarch *gdbarch, struct type *type)
}
}

-/* Return true if the expression stack is empty. */
+/* See expr.h. */

bool
dwarf_expr_context::stack_empty_p () const
@@ -2514,7 +2514,7 @@ dwarf_expr_context::stack_empty_p () const
return stack.empty ();
}

-/* Add a new piece to the composite on top of the stack. */
+/* See expr.h. */

std::shared_ptr<dwarf_entry>
dwarf_expr_context::add_piece (ULONGEST bit_size, ULONGEST bit_offset)
@@ -2550,7 +2550,7 @@ dwarf_expr_context::add_piece (ULONGEST bit_size, ULONGEST bit_offset)
}

-/* Evaluate the expression at ADDR (LEN bytes long). */
+/* See expr.h. */

void
dwarf_expr_context::eval (const gdb_byte *addr, size_t len)
@@ -2564,7 +2564,7 @@ dwarf_expr_context::eval (const gdb_byte *addr, size_t len)
gdb_assert (this->recursion_depth == old_recursion_depth);
}

-/* Helper to read a uleb128 value or throw an error. */
+/* See expr.h. */

const gdb_byte *
safe_read_uleb128 (const gdb_byte *buf, const gdb_byte *buf_end,
@@ -2576,7 +2576,7 @@ safe_read_uleb128 (const gdb_byte *buf, const gdb_byte *buf_end,
return buf;
}

-/* Helper to read a sleb128 value or throw an error. */
+/* See expr.h. */

const gdb_byte *
safe_read_sleb128 (const gdb_byte *buf, const gdb_byte *buf_end,
@@ -2588,6 +2588,8 @@ safe_read_sleb128 (const gdb_byte *buf, const gdb_byte *buf_end,
return buf;
}

+/* See expr.h. */
+
const gdb_byte *
safe_skip_leb128 (const gdb_byte *buf, const gdb_byte *buf_end)
{
@@ -2597,9 +2599,7 @@ safe_skip_leb128 (const gdb_byte *buf, const gdb_byte *buf_end)
return buf;
}

-/* Check that the current operator is either at the end of an
- expression, or that it is followed by a composition operator or by
- DW_OP_GNU_uninit (which should terminate the expression). */
+/* See expr.h. */

void
dwarf_expr_require_composition (const gdb_byte *op_ptr, const gdb_byte *op_end,
@@ -2627,8 +2627,7 @@ base_types_equal_p (struct type *t1, struct type *t2)
return TYPE_LENGTH (t1) == TYPE_LENGTH (t2);
}

-/* If <BUF..BUF_END] contains DW_FORM_block* with single DW_OP_reg* return the
- DWARF register number. Otherwise return -1. */
+/* See expr.h. */

int
dwarf_block_to_dwarf_reg (const gdb_byte *buf, const gdb_byte *buf_end)
@@ -2668,10 +2667,7 @@ dwarf_block_to_dwarf_reg (const gdb_byte *buf, const gdb_byte *buf_end)
return dwarf_reg;
}

-/* If <BUF..BUF_END] contains DW_FORM_block* with just DW_OP_breg*(0) and
- DW_OP_deref* return the DWARF register number. Otherwise return -1.
- DEREF_SIZE_RETURN contains -1 for DW_OP_deref; otherwise it contains the
- size from DW_OP_deref_size. */
+/* See expr.h. */

int
dwarf_block_to_dwarf_reg_deref (const gdb_byte *buf, const gdb_byte *buf_end,
@@ -2729,8 +2725,7 @@ dwarf_block_to_dwarf_reg_deref (const gdb_byte *buf, const gdb_byte *buf_end,
return dwarf_reg;
}

-/* If <BUF..BUF_END] contains DW_FORM_block* with single DW_OP_fbreg(X) fill
- in FB_OFFSET_RETURN with the X offset and return 1. Otherwise return 0. */
+/* See expr.h. */

int
dwarf_block_to_fb_offset (const gdb_byte *buf, const gdb_byte *buf_end,
@@ -2755,9 +2750,7 @@ dwarf_block_to_fb_offset (const gdb_byte *buf, const gdb_byte *buf_end,
return 1;
}

-/* If <BUF..BUF_END] contains DW_FORM_block* with single DW_OP_bregSP(X) fill
- in SP_OFFSET_RETURN with the X offset and return 1. Otherwise return 0.
- The matched SP register number depends on GDBARCH. */
+/* See expr.h. */

int
dwarf_block_to_sp_offset (struct gdbarch *gdbarch, const gdb_byte *buf,
@@ -2797,8 +2790,7 @@ dwarf_block_to_sp_offset (struct gdbarch *gdbarch, const gdb_byte *buf,
return 1;
}

-/* The engine for the expression evaluator. Using the context in this
- object, evaluate the expression between OP_PTR and OP_END. */
+/* See expr.h. */

void
dwarf_expr_context::execute_stack_op (const gdb_byte *op_ptr,
diff --git a/gdb/dwarf2/expr.h b/gdb/dwarf2/expr.h
index 3c404d8f83c..5170ac2df43 100644
--- a/gdb/dwarf2/expr.h
+++ b/gdb/dwarf2/expr.h
@@ -32,7 +32,9 @@ struct dwarf2_per_objfile;
its current state and its callbacks. */
struct dwarf_expr_context
{
- /* We should ever only pass in the PER_OBJFILE, while the ADDR_SIZE
+ /* Create a new context for the expression evaluator.
+
+ We should ever only pass in the PER_OBJFILE and the ADDR_SIZE
information should be retrievable from there. The PER_OBJFILE
contains a pointer to the PER_BFD information anyway and the
address size information must be the same for the whole BFD. */
@@ -40,6 +42,7 @@ struct dwarf_expr_context
int addr_size);
virtual ~dwarf_expr_context () = default;

+ /* Push ADDR onto the stack. */
void push_address (CORE_ADDR addr, bool in_stack_memory);

/* Evaluate the expression at ADDR (LEN bytes long) in a given PER_CU
@@ -88,14 +91,39 @@ struct dwarf_expr_context
/* Property address info used for the evaluation. */
const struct property_addr_info *addr_info = nullptr;

+ /* Evaluate the expression at ADDR (LEN bytes long). */
void eval (const gdb_byte *addr, size_t len);
+
+ /* Return the type used for DWARF operations where the type is
+ unspecified in the DWARF spec. Only certain sizes are
+ supported. */
struct type *address_type () const;
- void push (std::shared_ptr<dwarf_entry> value);
+
+ /* Push ENTRY onto the stack. */
+ void push (std::shared_ptr<dwarf_entry> entry);
+
+ /* Return true if the expression stack is empty. */
bool stack_empty_p () const;
+
+ /* Pop a top element of the stack and add as a composite piece
+ with an BIT_OFFSET offset and of a BIT_SIZE size.
+
+ If the following top element of the stack is a composite
+ location description, the piece will be added to it. Otherwise
+ a new composite location description will be created and
+ the piece will be added to that composite. */
std::shared_ptr<dwarf_entry> add_piece (ULONGEST bit_size,
ULONGEST bit_offset);
+
+ /* The engine for the expression evaluator. Using the context in
+ this object, evaluate the expression between OP_PTR and
+ OP_END. */
void execute_stack_op (const gdb_byte *op_ptr, const gdb_byte *op_end);
+
+ /* Pop the top item off of the stack. */
void pop ();
+
+ /* Retrieve the N'th item on the stack. */
std::shared_ptr<dwarf_entry> fetch (int n);

/* Fetch the result of the expression evaluation in a form of
@@ -138,18 +166,32 @@ struct dwarf_expr_context
read as an address in a given FRAME. */
CORE_ADDR read_addr_from_reg (struct frame_info *, int);

+/* Check that the current operator is either at the end of an
+ expression, or that it is followed by a composition operator or by
+ DW_OP_GNU_uninit (which should terminate the expression). */
void dwarf_expr_require_composition (const gdb_byte *, const gdb_byte *,
const char *);

+/* If <BUF..BUF_END] contains DW_FORM_block* with single DW_OP_reg* return the
+ DWARF register number. Otherwise return -1. */
int dwarf_block_to_dwarf_reg (const gdb_byte *buf, const gdb_byte *buf_end);

+/* If <BUF..BUF_END] contains DW_FORM_block* with just DW_OP_breg*(0) and
+ DW_OP_deref* return the DWARF register number. Otherwise return -1.
+ DEREF_SIZE_RETURN contains -1 for DW_OP_deref; otherwise it contains the
+ size from DW_OP_deref_size. */
int dwarf_block_to_dwarf_reg_deref (const gdb_byte *buf,
const gdb_byte *buf_end,
CORE_ADDR *deref_size_return);

+/* If <BUF..BUF_END] contains DW_FORM_block* with single DW_OP_fbreg(X) fill
+ in FB_OFFSET_RETURN with the X offset and return 1. Otherwise return 0. */
int dwarf_block_to_fb_offset (const gdb_byte *buf, const gdb_byte *buf_end,
CORE_ADDR *fb_offset_return);

+/* If <BUF..BUF_END] contains DW_FORM_block* with single DW_OP_bregSP(X) fill
+ in SP_OFFSET_RETURN with the X offset and return 1. Otherwise return 0.
+ The matched SP register number depends on GDBARCH. */
int dwarf_block_to_sp_offset (struct gdbarch *gdbarch, const gdb_byte *buf,
const gdb_byte *buf_end,
CORE_ADDR *sp_offset_return);
@@ -189,14 +231,17 @@ gdb_skip_leb128 (const gdb_byte *buf, const gdb_byte *buf_end)
return buf + bytes_read;
}

+/* Helper to read a uleb128 value or throw an error. */
extern const gdb_byte *safe_read_uleb128 (const gdb_byte *buf,
const gdb_byte *buf_end,
uint64_t *r);

+/* Helper to read a uleb128 value or throw an error. */
extern const gdb_byte *safe_read_sleb128 (const gdb_byte *buf,
const gdb_byte *buf_end,
int64_t *r);

+/* Helper to skip a leb128 value or throw an error. */
extern const gdb_byte *safe_skip_leb128 (const gdb_byte *buf,
const gdb_byte *buf_end);

--
2.17.1