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

This is the 2026-05-11 version of the proposal. [ Compare with previous version ] [ Return to the latest version ]

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: inline 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 inline operands. The number of inline operands is implied by the opcode. It may also receive 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 inline operands, if any, as a C-like function prototype. Each inline operand has one of the following types:

ubyte (unsigned 1-byte value)

uhalf (unsigned 2-byte value)

uword (unsigned 4-byte value)

ulong (unsigned 8-byte value)

sbyte (signed 1-byte value)

shalf (signed 2-byte value)

sword (signed 4-byte value)

slong (signed 8-byte value)

uleb (unsigned LEB128 value)

sleb (signed LEB128 value)

block (a block of bytes, encoded like DW_FORM_block)

block1 (a block of bytes, encoded like DW_FORM_block1)

address (an address in the default memory address space)

offset2 (2-byte offset to a DIE)

offset4 (4-byte offset to a DIE)

offset (4- or 8-byte offset to a DIE)

Following the operation heading is a stack diagram, showing the state of the stack before and after the operation, with the top of the stack at the top of the diagram, and the base of the stack 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.

Symbolic names are often given to the stack arguments and the stack result when it is considered to be helpful or meaningful. In the cases where no sybolic name would be meaningful, the generic names A, B, C, and D are used.

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

DW_OP_dup

DW_OP_drop

DW_OP_pick (ubyte 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 (ubyte VALUE)

DW_OP_const2u (uhalf VALUE)

DW_OP_const4u (uword VALUE)

DW_OP_const8u (ulong VALUE)

DW_OP_const1s (sbyte VALUE)

DW_OP_const2s (shalf VALUE)

DW_OP_const4s (sword VALUE)

DW_OP_const8s (slong VALUE)

DW_OP_constu (uleb VALUE)

DW_OP_consts(sleb VALUE)

DW_OP_constx (uleb INDEX)

DW_OP_const_type(uleb DIE_REF, block1 VALUE)

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

DW_OP_regval_type (uleb REG, uleb DIE_REF)

DW_OP_regval_bits (uleb 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 (uleb 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 (address A)

DW_OP_addrx (uleb INDEX)

DW_OP_fbreg (sleb OFFSET)

DW_OP_breg<n> (sleb OFFSET)

DW_OP_bregx (uleb REG, sleb OFFSET)

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

DW_OP_reg<n>

DW_OP_regx (uleb 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 (offset DIE_REF, sleb OFFSET)

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

DW_OP_composite

DW_OP_piece (uleb SIZE)

DW_OP_bit_piece (uleb SIZE, uleb OFFSET)

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

DW_OP_deref

DW_OP_deref_size (ubyte SIZE)

DW_OP_deref_type (ubyte SIZE, uleb DIE_REF)

DW_OP_xderef

DW_OP_xderef_size (ubyte SIZE)

DW_OP_xderef_type (ubyte SIZE, uleb 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 (shalf SKIP)

no stack effects

DW_OP_bra (shalf SKIP)

DW_OP_call2 (uhalf DIE_REF)

DW_OP_call4 (uword DIE_REF)

DW_OP_call_ref (offset DIE_REF)

stack effects by agreement

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

DW_OP_convert (uleb DIE_REF)

DW_OP_reinterpret (uleb 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 (uleb EXTENDED_OPCODE)

stack effects defined by extended operation

DW_OP_user_extended (uleb 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.