Release hardware.inc version 4.10

[Rangi42]

Before merging, correct the date in HISTORY.md! Then, do "squash and merge"!

Although this is a large PR, it does not break any backwards compatibility. All the pre-existing constants are still defined. This should be a drop-in replacement for anyone using hardware.inc 4.9.2.

The changes here fall into a few categories:

New constants

• A HARDWARE_INC_VERSION string constant (currently "4.10.0") to provide more flexibility than the rev_Check_hardware_inc macro.

• We now consistently define <REG>B_<FIELD> for bit values (0-7, to be used with bit, set, res) and <REG>F_<FIELD> for flag values (to be used with and, or, xor). Some <REG>F_<FIELD> are also meant as values (to be used with ld). Previously many registers had flags but not bits, or sometimes vice-versa, or lacked any field bits/flags at all even though Pan Docs described some.

• Some new registers: rKEY0 ($FF4C) and rBANK ($FF50). These are boot ROM registers which were already documented in Pan Docs, but only defined in gb-bootroms.

• A new rRTCREG ($A000) register that is affected by rRAMB and rRTCLATCH for MBC3. (pokecrystal's hardware_constants.asm had called this MBC3RTC.)

• Some new preferred aliases have been defined:

  • rJOYP for rP1: Pan Docs already listed this as an alias, and used it more widely than P1 (e.g. in the stop diagram), and it's more human-readable.
  • rVDMA_* for rHDMA1-5: This continues the pattern of how we added rAUD* aliases for the rNRxx registers a long time ago (before the initial commit in this repository). I used "VDMA" here for "video DMA", since "horizontal/HBlank DMA" and "general DMA" are the two modes it can take.
    • rVDMA_SRC_HIGH for rHDMA1
    • rVDMA_SRC_LOW for rHDMA2
    • rVDMA_DEST_HIGH for rHDMA3
    • rVDMA_DEST_LOW for rHDMA4
    • rVDMA_LEN for rHDMA5
  • rWBK for rSVBK aka rSMBK: This was suggested in rHDMAx alternative names #36, and makes more sense as "WRAM bank" (pairing with rVBK for "VRAM bank").
  • IEB_JOYPAD and IEF_JOYPAD for IEB_HILO and IEF_HILO: This is the Joypad interrupt, not the "hilo" interrupt.
  • OBJ_B for sizeof_OAM_ATTRS: This matches the SCRN_X_B and SCRN_Y_B byte-size constants, and avoids a one-off lowercase "sizeof_*".

• PADF_SWAP_* constants as alternatives to the existing PADF_* constants, with a swapped convention of putting Control Pad bits in the low nybble instead of the high nybble.

• More constants are defined related to tiles, palettes and colors, grouped with the screen-related constants.

• A complete list new newly available constants is at https://pastebin.com/V4eq0zPe.

Deprecations

Again, although nothing has been removed, some things have been commented as "deprecated", with preferred alternatives available from RGBASM, RGBLINK, and RGBFIX.

• Memory region constants, like _RAMBANK: since RGBASM 0.7.0, you can do STARTOF(WRAMX) instead. Note that the actual value gets resolved by RGBLINK, since some settings (like -d/--dmg) can affect which section types span which memory.

• Cartridge header constants, like NINTENDO_LOGO or CART_ROM_* MBC values: You can reserve a SECTION for your cartridge header filled with $00s, and should use RGBFIX to assign appropriate values inside it (including correct checksums).

Reformatting and reorganizing

• Comments take up less vertical space. Heading comments have changed from this:

  ;***************************************************************************
  ;*
  ;* Description
  ;*
  ;***************************************************************************

  to this:

  ;******************************************************************************
  ; Description
  ;******************************************************************************

  And subheading comments have changed from this:

  ; --
  ; -- NAME ($ADDR)
  ; -- Description
  ; --

  to this:

  ; -- NAME ($ADDR) -------------------------------------------------------------
  ; Description

• Register readability/writeability indicators have changed from (R/W) (R) (W) to [r/w] [ro] [wo].

• Lowercase def equ instead of DEF EQU so the all-caps constant names stand out more.

• Associated/dependent constants are indented. Now that RGBASM uses def to introduce definitions, this is legal, and helps to indicate a "hierarchy" of constants (e.g. flag values being derived from bit values).

• Use equ instead of rb to define OAM object field offsets, so we won't be disturbing the value of _RS for the user.

• Comments noting which addresses in the $FF00-$FF7F range are "unused", so they don't look like oversights.

• The history change log has moved from the top of the file to its own HISTORY.md file. This makes the actual file more compact, and enables Markdown formatting. In future we may want to backfill the changelog with more detail now that it wouldn't be bloating the main file.

• Removed the links to Jeff Frohwein's devrs.com because it's now just a HostGator default page, and there's no need to link to his old hardware.inc v2.3 when we have it tagged already.

Resolutions

This resolves many open issues that have been neglected, some for years:

• Fixes rHDMAx alternative names #36: rHDMA1-5 now have alternative names, and we've added rWBK, CGB palette constants, and BGP_SGB_TRANSFER ($E4).
• Fixes PADF_* and PADB_* constants don't represent hardware values #37: The PADF_* constants are here to stay, and we've added PADF_SWAP_* constants to make it clear that this is a convention, not an inescapable fact of the hardware.
• Fixes Companion file for conveniences #38: We're not making judgement calls on what's a "convenience" versus what's fundamental; it all goes in one useful file. Conveniences beyond what such a file would provide are in gb-boilerplate and gb-starter-kit, as well as macro packs like rgbds-structs.
• Fixes Defining F values based on B values #42: Flag values are defined as shifted Bit values when possible. We decided against using macros because def REGF_FIELD equ 1 << REGB_FIELD is minimal boilerplate and makes both names easily greppable.
• Fixes Define more MASK constants #46: Mask constants are now consistently defined for all registers.
• Fixes Missing rJOYP alias for rP1 #47: rJOYP is now defined and preferred to rP1.
• Fixes Why "HILO" instead of "JOYPAD" for rIE? #48: We now define IEB/F_JOYPAD and have deprecated IEB/F_HILO.
• Fixes Constants for the size (in bytes) and length (in pixels) of a tile #49: We now define TILE_X and TILE_Y for the tile width and height of 8 pixels (comparable to SCRN_X and SCRN_Y), and TILE_B for the 16-byte size.

[Rangi42]

(I don't have review-request permissions in this repository, so: @ISSOtm @avivace @AntonioND @nitro2k01 @FredrIQ @vulcandth maybe in the next week or so y'all can take a look at this?)

[ISSOtm]

Thank you very much for this highly thorough change!

The nature of a review means I am only going to point out the things that I disagree with, but I have to say that I'm a big fan of the improvements here, including some of the more intuitive names.

[ISSOtm]

Looks good to me now!