search

gbdev / rgbds

Rednex Game Boy Development System - An assembly toolchain for the Nintendo Game Boy and Game Boy Color
https://rgbds.gbdev.io
MIT License
1.35k stars 172 forks source link

Documentation of `jr` does not match the assembler behavior #1020

Closed Lokathor closed 2 years ago

Lokathor commented 2 years ago

the jr operation is documented as being one of either 

jr e8
jr cc, e8

Where e8 is "8-bit offset".

However, when a number is passed as the argument to jr that number is taken as an absolute address, then a relative address is calculated from that.

In other words, jr 3 doesn't perform a relative jump of +3 bytes, it tries to perform a relative jump to address $0003.

I don't think the assembler should change at all, but the manual should be updated to reflect this.

aaaaaa123456789 commented 2 years ago

Why would you expect anything different? All expressions behave the same. Having jr 3 do something other than jr 3 + 0 (or any other expression that evaluates to 3, like a label at 3, or rIE - $fffc, or anything else) would be confusing.

Lokathor commented 2 years ago

Because the docs say it takes an e8.

Again, I don't want the assembler to change, I just want the docs to better explain the usage.

evie-calico commented 2 years ago

The assembly manual should describe the usage, not the underlying encoding, so e8 is just wrong as any 16-bit value is valid

Rangi42 commented 2 years ago

Except any label isn't valid, only the ones that can be encoded as an e8.

The full JR e8 description is:

Relative Jump by adding e8 to the address of the instruction following the JR. To clarify, an operand of 0 is equivalent to no jumping.

If it said JR n16, that would have to say something like "Relative Jump by adding (the address of the instruction following the JR - e8) to the..." which sounds even more confusing than seeing e8 where a label is used.

evie-calico commented 2 years ago

But that implies that the syntax is jr 2, which would skip 2 bytes, when in reality it’s jumping to $0002. The RGBDS docs should only be concerned with the syntax RGBDS users will be writing, and explaining that labels are converted into those offsets is important.

For example, the following part of the JR documentation is straight-up wrong:

To clarify, an operand of 0 is equivalent to no jumping.

Because an operand of 0 in RGBDS jumps to $0000

Rangi42 commented 2 years ago

@ISSOtm How do you want this to be resolved?