FF55 (rHDMA5) contradicts Pan Docs

[nummacway]

Pan Docs say:

Reading from Register FF55 [...], a value of $FF indicates that the transfer has completed.

and

Reading Bit 7 of FF55 can be used to confirm if the DMA transfer is active (1=Not Active, 0=Active).

hardware.inc says bit 7 is 0 when not busy:

def B_VDMA_LEN_BUSY equ 7 ; on read: is a VRAM DMA active?
    def VDMA_LEN_BUSY equ 1 << B_VDMA_LEN_BUSY
        def VDMA_LEN_NO  equ 0 << B_VDMA_LEN_BUSY
        def VDMA_LEN_YES equ 1 << B_VDMA_LEN_BUSY

[Rangi42]

Thanks! hardware.inc v4.10 added a lot of per-bit-value constants, but got those two backwards. Just have to swap them around:

        def VDMA_LEN_YES equ 0 << B_VDMA_LEN_BUSY
        def VDMA_LEN_NO  equ 1 << B_VDMA_LEN_BUSY

[pinobatch]

🚲️🛖️ Is there a reason why they're called YES and NO rather than RUN and STOP or the like? Compare to how Yes/No/Cancel buttons in alert boxes were deprecated in favor of labeling buttons with distinct verbs like Save/Discard/Cancel or Try Again/Cancel.

[Rangi42]

@pinobatch Want to open an issue listing suggested naming change(s) like that, for the next major release?

[nummacway]

Thanks! hardware.inc v4.10 added a lot of per-bit-value constants

This is quite inconsistent.

• rVBK has no B_VBK_BANK equ 0 (not that it makes much sense, but other registers like the entirely useless BANK register do have one for B_BANK_0)
• DMG color mapping (rBGP, rOBP0, rOBP1) color IDs have no constants at all (but shades do)
• While there are trivial bit constants for many rLCDC bits, no such constants exist for rSTAT and most OAMA_FLAGS
• While rLCDC has distinct constants for mask and whatever a set bit means for that bit, rBANK and OAMA_FLAGS do not have this

This is only for video registers. (As part of my "cheat sheet project", I'm reading through all the GBDEV documentation to make a proper A4 cheat sheet on every topic, for a total of 4 or 5. After finishing the instruction cheat sheet, I'm currently working on video and RGBASM syntax.)

[Rangi42]

rVBK has no B_VBK_BANK equ 0 (not that it makes much sense, but other registers like the entirely useless rBANK register do have one for B_BANK_0).

rVBK has def VBK_BANK equ %0000000_1 ; mapped VRAM bank [r/w], which is a mask for its meaningful value, same as rWBK has def WBK_BANK equ %00000_111 ; mapped WRAM bank (0-7) [r/w]. rBANK is a Boolean register, and those should generally have named constants for both values because there's no consistent convention of what 0 and 1 mean (as you pointed out).

[Rangi42]

DMG color mapping (rBGP, rOBP0, rOBP1) color IDs have no constants at all (but shades do)

Good point, added in #95.

[Rangi42]

• While there are trivial bit constants for many rLCDC bits, no such constants exist for rSTAT and most OAMA_* flags.
• While rLCDC has distinct constants for mask and whatever a set bit means for that bit, rBANK and OAMA_* flags do not have this.

@pinobatch Wouldn't all such constants be trivial 0=no 1=yes Booleans? IIRC when I was adding new constants in v4.10, I usually just added bit constants expecting people to do bit/res/set B_STAT_LYC or ld a, 0/1 << B_STAT_LYC or so on, and only added named constants for the values when 0/1 would have no clear meaning (quick, which one puts the window at $9800?) or for completeness (hence the OFF/ON constants even for rLCDC's more obvious bits).