Module me.hugmanrique.cartage
Package me.hugmanrique.cartage.gb

Interface GBCartridge.Header

Enclosing interface:
GBCartridge
public static interface GBCartridge.Header
The header of a Game Boy cartridge. Changes to the header are reflected in the cartridge, and vice-versa.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static int
    LOGO_LENGTH
    The number of bytes reserved for the Nintendo logo.
    static int
    MAX_RAM_BYTES
    The maximum RAM size, in bytes.
    static int
    MAX_ROM_BYTES
    The maximum ROM size, in bytes.
    static int
    MIN_ROM_BYTES
    The minimum ROM size, in bytes.

  • Method Summary

    Modifier and Type
    Method
    Description
    byte
    checksum()
    Returns the checksum of some header data.
    byte
    computeChecksum()
    Computes the checksum of some header data (as returned by checksum()) from the current header contents.
    boolean
    destination()
    Returns the destination code.
    short
    entryPoint()
    Returns the address to which the console's boot procedure jumps after initialization.
    byte
    gbc()
    Returns the value of the GBC flag.
    static byte[]
    getValidLogo()
    Returns the Nintendo logo expected by the console.
    short
    globalChecksum()
    Returns the checksum of the entire ROM.
    boolean
    hasColorFunctions()
    Returns whether the cartridge supports GBC functions.
    boolean
    hasSuperFunctions()
    Returns whether the cartridge supports SGB functions.
    boolean
    japaneseDistribution()
    Returns whether the cartridge is supposed to be sold in Japan.
    short
    licensee()
    Returns the licensee code, which indicates the company or publisher of the cartridge.
    byte[]
    logo()
    Returns the Nintendo logo bitmap.
    void
    logo​(byte[] dest)
    Copies the Nintendo logo bitmap into the given array.
    String
    manufacturer()
    Returns the 4-character uppercase manufacturer code, only present in GBC cartridges.
    byte
    ramSize()
    Returns the RAM size code.
    int
    ramSizeBytes()
    Returns the RAM size, if any.
    boolean
    requiresColor()
    Returns whether the cartridge requires a GBC console to run.
    byte
    romSize()
    Returns the ROM size code.
    int
    romSizeBytes()
    Returns the ROM size.
    byte
    setChecksum()
    Sets the header checksum to the value returned by computeChecksum().
    void
    setChecksum​(byte checksum)
    Sets the header checksum.
    void
    setDestination​(boolean destination)
    Sets the destination code.
    void
    setEntryPoint​(short entryPoint)
    Sets the entry point address.
    void
    setGbc​(byte value)
    Sets the GBC flag.
    void
    setGlobalChecksum​(short checksum)
    Sets the global checksum.
    void
    setLogo​(byte[] source)
    Sets the Nintendo logo bitmap.
    void
    setManufacturer​(String manufacturer)
    Sets the cartridge manufacturer.
    void
    setNewLicensee​(short licensee)
    Sets the licensee code, following the new format.
    void
    setOldLicensee​(byte licensee)
    Sets the licensee code, following the old format.
    void
    setRamSize​(byte code)
    Sets the RAM size code.
    void
    setRomSize​(byte code)
    Sets the ROM size code.
    void
    setSgb​(byte value)
    Sets the SGB flag.
    void
    setTitle​(String title)
    Sets the cartridge title.
    void
    setType​(GBCartridge.Type type)
    Sets the cartridge type.
    void
    setValidLogo()
    Sets the valid Nintendo logo.
    void
    setVersion​(byte version)
    Sets the cartridge version.
    byte
    sgb()
    Returns the value of the SGB flag.
    String
    title()
    Returns the 16-character uppercase cartridge title.
    @Nullable GBCartridge.Type
    type()
    Specifies the type of the cartridge.
    byte
    version()
    Returns the cartridge version.

  • Field Details

    • LOGO_LENGTH

      static final int LOGO_LENGTH
      The number of bytes reserved for the Nintendo logo.
      See Also:
      Constant Field Values

    • MIN_ROM_BYTES

      static final int MIN_ROM_BYTES
      The minimum ROM size, in bytes.
      See Also:
      Constant Field Values

    • MAX_ROM_BYTES

      static final int MAX_ROM_BYTES
      The maximum ROM size, in bytes.
      See Also:
      Constant Field Values

    • MAX_RAM_BYTES

      static final int MAX_RAM_BYTES
      The maximum RAM size, in bytes.
      See Also:
      Constant Field Values

  • Method Details

    • entryPoint

      short entryPoint()
      Returns the address to which the console's boot procedure jumps after initialization.

      The entry point area is a 4-byte region whose sole purpose is to jump to this address. It usually contains a NOP instruction followed by a JP or CALL.

      Returns:
      the entry point address
      Throws:
      IllegalStateException - if the entry point area contains no JP or CALL instruction

    • setEntryPoint

      void setEntryPoint​(short entryPoint)
      Sets the entry point address. This writes a NOP instruction followed by an unconditional jump to the given address.
      Parameters:
      entryPoint - the entry point address

    • getValidLogo

      static byte[] getValidLogo()
      Returns the Nintendo logo expected by the console.
      Returns:
      a copy of the valid logo
      See Also:
      for details on verification

    • logo

      byte[] logo()
      Returns the Nintendo logo bitmap.

      If incorrect, the console's boot procedure locks up in an infinite loop. Some console models partially verify the contents of the logo. For example, the GBC only verifies the first 18 bytes of the returned array.

      Returns:
      a copy of the logo

    • logo

      void logo​(byte[] dest)
      Copies the Nintendo logo bitmap into the given array.
      Parameters:
      dest - the destination array
      Throws:
      IllegalArgumentException - if the length of dest is not LOGO_LENGTH
      See Also:
      for details on verification

    • setLogo

      void setLogo​(byte[] source)
      Sets the Nintendo logo bitmap.
      Parameters:
      source - the logo
      Throws:
      IllegalArgumentException - if the length of source is not LOGO_LENGTH
      See Also:
      for details on verification

    • setValidLogo

      void setValidLogo()
      Sets the valid Nintendo logo.
      See Also:
      to get a copy of the valid logo

    • title

      String title()
      Returns the 16-character uppercase cartridge title.
      Returns:
      the cartridge title

    • setTitle

      void setTitle​(String title)
      Sets the cartridge title.
      Parameters:
      title - the cartridge title
      Throws:
      IllegalArgumentException - if the value has a length greater than 16, or contains non-ASCII or non-uppercase characters

    • manufacturer

      String manufacturer()
      Returns the 4-character uppercase manufacturer code, only present in GBC cartridges.
      Returns:
      the manufacturer code

    • setManufacturer

      void setManufacturer​(String manufacturer)
      Sets the cartridge manufacturer.
      Parameters:
      manufacturer - the cartridge manufacturer
      Throws:
      IllegalArgumentException - if the value has a length greater than 4, or contains non-ASCII or non-uppercase characters

    • gbc

      byte gbc()
      Returns the value of the GBC flag.
      Returns:
      the GBC flag value

    • setGbc

      void setGbc​(byte value)
      Sets the GBC flag.
      Parameters:
      value - the GBC flag

    • hasColorFunctions

      boolean hasColorFunctions()
      Returns whether the cartridge supports GBC functions.
      Returns:
      true if the cartridge supports GBC functions
      See Also:
      to check if the cartridge requires a GBC to run

    • requiresColor

      boolean requiresColor()
      Returns whether the cartridge requires a GBC console to run.
      Returns:
      true if the cartridge requires a GBC to run

    • licensee

      short licensee()
      Returns the licensee code, which indicates the company or publisher of the cartridge.
      Returns:
      the licensee code

    • setOldLicensee

      void setOldLicensee​(byte licensee)
      Sets the licensee code, following the old format.
      Parameters:
      licensee - the licensee code

    • setNewLicensee

      void setNewLicensee​(short licensee)
      Sets the licensee code, following the new format.
      Parameters:
      licensee - the licensee code

    • sgb

      byte sgb()
      Returns the value of the SGB flag.
      Returns:
      the SGB flag value

    • setSgb

      void setSgb​(byte value)
      Sets the SGB flag.
      Parameters:
      value - the SGB flag

    • hasSuperFunctions

      boolean hasSuperFunctions()
      Returns whether the cartridge supports SGB functions.
      Returns:
      true if the cartridge supports SGB functions

    • type

      @Nullable GBCartridge.Type type()
      Specifies the type of the cartridge.
      Returns:
      the cartridge type, or null if unknown

    • setType

      void setType​(GBCartridge.Type type)
      Sets the cartridge type.
      Parameters:
      type - the cartridge type

    • romSize

      byte romSize()
      Returns the ROM size code.
      Returns:
      the ROM size code

    • romSizeBytes

      int romSizeBytes()
      Returns the ROM size.
      Returns:
      the ROM size, in bytes

    • setRomSize

      void setRomSize​(byte code)
      Sets the ROM size code.

      Note that the cartridge may not support this configuration. In particular, sizes larger than 32 KB require a memory bank controller.

      Parameters:
      code - the ROM size code
      Throws:
      IllegalArgumentException - if the code is invalid

    • ramSize

      byte ramSize()
      Returns the RAM size code.
      Returns:
      the RAM size code

    • ramSizeBytes

      int ramSizeBytes()
      Returns the RAM size, if any.
      Returns:
      the RAM size, in bytes
      Throws:
      IllegalStateException - if the current RAM size code is invalid

    • setRamSize

      void setRamSize​(byte code)
      Sets the RAM size code.

      Note that the cartridge may not support this configuration.

      Parameters:
      code - the RAM size code
      Throws:
      IllegalArgumentException - if the code is invalid

    • destination

      boolean destination()
      Returns the destination code.
      Returns:
      the destination code

    • japaneseDistribution

      boolean japaneseDistribution()
      Returns whether the cartridge is supposed to be sold in Japan.
      Returns:
      true if the cartridge is solely distributed in Japan

    • setDestination

      void setDestination​(boolean destination)
      Sets the destination code.
      Parameters:
      destination - the destination code

    • version

      byte version()
      Returns the cartridge version.
      Returns:
      the version

    • setVersion

      void setVersion​(byte version)
      Sets the cartridge version.
      Parameters:
      version - the version

    • checksum

      byte checksum()
      Returns the checksum of some header data. If incorrect, the console's boot procedure locks up in an infinite loop.
      Returns:
      the header checksum

    • computeChecksum

      byte computeChecksum()
      Computes the checksum of some header data (as returned by checksum()) from the current header contents.
      Returns:
      the computed header checksum

    • setChecksum

      void setChecksum​(byte checksum)
      Sets the header checksum.
      Parameters:
      checksum - the header checksum

    • setChecksum

      byte setChecksum()
      Sets the header checksum to the value returned by computeChecksum().
      Returns:
      the computed checksum
      See Also:
      to compute, but not overwrite, the header checksum

    • globalChecksum

      short globalChecksum()
      Returns the checksum of the entire ROM. Unlike the header checksum, the console boots even if incorrect.
      Returns:
      the global checksum

    • setGlobalChecksum

      void setGlobalChecksum​(short checksum)
      Sets the global checksum.
      Parameters:
      checksum - the global checksum