Issue 260127.1: Standardize Operation Headings

Author:	Ben Woodard
Champion:
Date submitted:	2026-01-27
Date revised:	2026-05-11
Date closed:	2026-06-08
Type:	Editorial
Status:	Accepted
DWARF version:	6

Background

This proposal is editorial in nature: it does not intend to change the meaning of any DWARF constructs, but merely to standardize the presentation of the existing DWARF operations to facilitate understanding.

It is believed that tool authors referring to the the standard would find it much easier to understand if each operand followed a standard template, rather than explaining these in the textual description of the operand. This issue proposes such a template and converts each operand to that template.

DWARF operations potentially have three sources of input: immediate operands, which are encoded in their byte stream; operands on the stack; and the context in which they are executed. They can also modify the stack and leave items on the stack. For every operator each of these sources of input, output, and side effects are specified in a standardized format similar to how other stack machine operations have been documented in the past.

Proposed Changes

In Chapter 3 replace the following paragraph:

A DWARF expression is encoded as a stream of operations, each consisting of an opcode followed by zero or more literal operands. The number of operands is implied by the opcode.

With:

A DWARF expression is encoded as a stream of operations, each operation consisting of an opcode followed by zero or more immediate operands. The number of immediate operands and their encodings are implied by the opcode. It may also consume operands from the stack and make use of information from its evaluation context.

The description of each operation begins with a heading that shows the name of the operation and its immediate operands, if any, as a C-like function prototype. Each immediate operand is encoded according to one of the form codes given in Section 8.5.5 "Classes and Forms". (For improved readability, the form codes in these descriptions are given here without the DW_FORM_ prefix.)

Following the operation heading is a stack diagram showing the state of the stack before and after the operation. The top of the stack is at the top of the diagram, and the base of the stack is shown as an open rectangle at the bottom of the diagram. In some cases, where the stack diagrams are the same for a group of operations, the diagram is given at the top of the section.

In Section 3.2, replace the operation headings and add stack diagrams, as follows:

DW_OP_dup

DW_OP_drop

DW_OP_pick (unsigned data1 N)

DW_OP_over

DW_OP_swap

DW_OP_rot

In section 3.3, add a stack diagram for the section, and replace the operation headings as follows:

DW_OP_lit0, DW_OP_lit1, ..., DW_OP_lit31

DW_OP_const1u (unsigned data1 VALUE)

DW_OP_const2u (unsigned data2 VALUE)

DW_OP_const4u (unsigned data4 VALUE)

DW_OP_const8u (unsigned data8 VALUE)

DW_OP_const1s (signed data1 VALUE)

DW_OP_const2s (signed data2 VALUE)

DW_OP_const4s (signed data4 VALUE)

DW_OP_const8s (signed data8 VALUE)

DW_OP_constu (udata VALUE)

DW_OP_consts (sdata VALUE)

DW_OP_constx (addrx INDEX)

DW_OP_const_type (ref_udata DIE_REF, block1 VALUE)

In section 3.4, replace the operation headings and add stack diagrams, as follows:

DW_OP_regval_type (udata REG, ref_udata DIE_REF)

DW_OP_regval_bits (udata NBITS)

In section 3.5, move the unary operations into a new subsection "3.5.1 Unary Operations". Add a stack diagram for the subsection, and replace the operation headings as follows:

DW_OP_abs

DW_OP_neg

DW_OP_not

Move the binary operations into a new subsection "3.5.2 Binary Operations". Add a stack diagram for the subsection, and replace the operation headings as follows:

DW_OP_and

DW_OP_div

DW_OP_minus

DW_OP_mod

DW_OP_mul

DW_OP_or

DW_OP_plus

DW_OP_shl

DW_OP_shr

DW_OP_shra

DW_OP_xor

Move the DW_OP_plus_uconst operation into a new subsection "3.5.3 Add Constant Operation". Replace the operation heading and add a stack diagram, as follows:

DW_OP_plus_uconst (udata B)

In section 3.6, replace the operation headings and add stack diagrams, as follows:

DW_OP_push_object_location

DW_OP_form_tls_location

DW_OP_call_frame_cfa

DW_OP_push_lane

In section 3.7, replace the operation headings and add stack diagrams, as follows:

DW_OP_addr (addr A)

DW_OP_addrx (addrx INDEX)

DW_OP_fbreg (sdata OFFSET)

DW_OP_breg<n> (sdata OFFSET)

DW_OP_bregx (udata REG, sdata OFFSET)

In section 3.8, replace the operation headings and add stack diagrams, as follows:

DW_OP_reg<n>

DW_OP_regx (udata REG)

In section 3.9, replace the operation headings and add stack diagrams, as follows:

DW_OP_undefined

In section 3.10, replace the operation headings and add stack diagrams, as follows:

DW_OP_implicit_value (block VALUE)

DW_OP_stack_value

In section 3.11, replace the operation heading and add a stack diagrams, as follows:

DW_OP_implicit_pointer (ref_addr DIE_REF, sdata OFFSET)

In section 3.12, replace the operation headings and add stack diagrams, as follows:

DW_OP_composite

DW_OP_piece (udata SIZE)

DW_OP_bit_piece (udata SIZE, udata OFFSET)

In section 3.13, replace the operation headings and add stack diagrams, as follows:

DW_OP_deref

DW_OP_deref_size (unsigned data1 SIZE)

DW_OP_deref_type (unsigned data1 SIZE, ref_udata DIE_REF)

DW_OP_xderef

DW_OP_xderef_size (unsigned data1 SIZE)

DW_OP_xderef_type (unsigned data1 SIZE, ref_udata DIE_REF)

In section 3.14, replace the operation headings and add stack diagrams, as follows:

DW_OP_offset

DW_OP_bit_offset

In section 3.15, replace the operation headings and add stack diagrams, as follows:

DW_OP_le, DW_OP_ge, DW_OP_eq, DW_OP_lt, DW_OP_gt, DW_OP_ne

DW_OP_skip (signed data2 SKIP)

no stack effects

DW_OP_bra (signed data2 SKIP)

DW_OP_call2 (ref2 DIE_REF)

DW_OP_call4 (ref4 DIE_REF)

DW_OP_call_ref (ref_addr DIE_REF)

stack effects by agreement

In section 3.16, replace the operation headings and add stack diagrams, as follows:

DW_OP_convert (ref_udata DIE_REF)

DW_OP_reinterpret (ref_udata DIE_REF)

In section 3.17, replace the operation headings as follows:

DW_OP_nop

no stack effects

DW_OP_entry_value (block EXPR)

stack result by agreement

DW_OP_extended (udata EXTENDED_OPCODE)

stack effects defined by extended operation

DW_OP_user_extended (udata EXTENDED_OPCODE)

stack effects defined by extended operation

---

2026-03-30: Accepted in principle; will revise to use drawings as shown in op-diagrams.pdf.

2026-04-29: Updated some of the introductory material and added stack diagrams.

2026-05-10: Editorial correction: "inline parameters" should be "inline operands".

2026-05-11: Revised operation headings and stack drawings. Changed "parameters (on the stack)" to "operands". Fixed type of DIE_REF operand for DW_OP_const_type. Defined block and block1 operand types the same as corresponding FORM codes.

2026-05-19: Revised: Change "inline operands" to "immediate operands". Used form names for immediate operand representations.

2026-06-08: Accepted. A subsequent proposal may introduce signed/unsigned variants of DW_FORM_data[1248], which could replace the use of "signed data1", etc., here.