User range

From Infinity Wiki
Jump to: navigation, search

Two fields in the Note format have user ranges:

  • The chunk_type field of note chunks.
  • The widecode operand of DW_OP_GNU_wide_op.

This means that certain ranges of values for these fields have been reserved for internal use by Note consumers. Why? Well, it's likely that note consumers may wish to modify notes internally for easier processing. The two fields currently defined mean:

  • Note consumers MAY internally annotate notes with extra chunks.
  • Note consumers MAY internally rewrite bytecode with custom operations.

Having specific ranges of values to do this means note consumers can be sure that future additions to Infinity will not break their existing code. They are protected because:

  • Outside of note consumers, notes MUST NOT contain user-ranged fields with these values.
  • Note consumers SHOULD reject notes they load containing user-ranged fields with these values as INVALID.

To understand which values are in user ranges you need to understand LEB128 encoding. All fields with user ranges are encoded as unsigned LEB128. If the bit below the most significant bit of the last byte of the encoded uleb128 value is set (x1xxxxxx) then the value is in a user range. If that bit is clear (x0xxxxxx)then the value is not in a user range and may be used by future additions to Infinity.

Code

In C-like pseudo-code, if the uleb128 value is in an array of bytes:

byte[N] value

then:

in_user_range = ((value[N - 1] & 0x40) != 0)

The first 16384 values

Decimal ULEB128 Range owner
First value Last value First value Last value
0 63 00 3f SYSTEM
64 127 40 7f USER
128 8191 80 01 ff 3f SYSTEM
8192 16383 80 40 ff 7f USER

If your consumer needs more than 8256 internal values then calculate more ranges until you have enough.