Module me.hugmanrique.cartage
Package me.hugmanrique.cartage.gba

Interface GBACartridge.Header

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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static int
    ENTRY_INSTRUCTION_ADDR
    The address at which a B instruction branching to the start address of the cartridge is written.
    static int
    LOGO_LENGTH
    The number of bytes reserved for the Nintendo logo.

  • Method Summary

    Modifier and Type
    Method
    Description
    byte
    checksum()
    Returns the checksum of some header data.
    void
    clearDacs()
    Disables the debugging handler.
    String
    code()
    Returns the 4-character uppercase UTTD code.
    byte
    computeChecksum()
    Computes the checksum of some header data (as returned by checksum()) from the current header contents.
    @Nullable GBACartridge.DACSType
    dacs()
    Returns the type of the DACS memory, if any.
    @Nullable GBACartridge.Destination
    destination()
    Returns the cartridge distribution region, derived from the UTTD code.
    int
    entryPoint()
    Returns the address to which the console's boot procedure jumps after initialization.
    static byte[]
    getValidLogo()
    Returns the Nintendo logo expected by the console, with debugging mode disabled.
    String
    licensee()
    Returns the 2-character uppercase licensee code, which indicates the company or publisher of the cartridge; also known as the maker code.
    byte[]
    logo()
    Returns the Nintendo logo bitmap.
    void
    logo​(byte[] dest)
    Copies the Nintendo logo into the given array.
    byte
    requiredConsole()
    Returns the required console model to use the cartridge; also known as the main unit code.
    byte
    setChecksum()
    Sets the header checksum to the value returned by computeChecksum().
    void
    setChecksum​(byte checksum)
    Sets the header checksum.
    void
    setCode​(String code)
    Sets the UTTD code.
    void
    setDacs​(GBACartridge.DACSType type)
    Enables the debugging handler and sets the given DACS memory type.
    void
    setDestination​(GBACartridge.Destination destination)
    Sets the distribution region.
    void
    setEntryPoint​(int address)
    Sets the entry point address.
    void
    setLicensee​(String value)
    Sets the licensee code.
    void
    setLogo​(byte[] source)
    Sets the Nintendo logo bitmap.
    void
    setRequiredConsole​(byte value)
    Sets the required console model.
    void
    setShortTitle​(String value)
    Sets the short cartridge title.
    void
    setTitle​(String title)
    Sets the cartridge title.
    void
    setType​(GBACartridge.Type type)
    Sets the cartridge type.
    void
    setValidLogo()
    Sets the valid Nintendo logo, with debugging mode disabled.
    void
    setVersion​(byte version)
    Sets the cartridge version.
    String
    shortTitle()
    Returns the 2-character uppercase short cartridge title, derived from the UTTD code.
    String
    title()
    Returns the 12-character uppercase cartridge title.
    @Nullable GBACartridge.Type
    type()
    Returns the type of the cartridge, derived from the UTTD code.
    byte
    version()
    Returns the cartridge version.

  • Field Details

    • ENTRY_INSTRUCTION_ADDR

      static final int ENTRY_INSTRUCTION_ADDR
      The address at which a B instruction branching to the start address of the cartridge is written.
      See Also:
      Constant Field Values

    • LOGO_LENGTH

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

  • Method Details

    • entryPoint

      int entryPoint()
      Returns the address to which the console's boot procedure jumps after initialization.
      Returns:
      the entry point address, in bytes
      Throws:
      IllegalStateException - if the entry point instruction is not a B instruction

    • setEntryPoint

      void setEntryPoint​(int address)
      Sets the entry point address. This writes a B instruction at ENTRY_INSTRUCTION_ADDR with a relative word offset to the given address.

      The ARM7TDMI branch instruction contain a signed 24-bit word offset. Therefore, the minimum and maximum entry point addresses are 0x6000010 and 0xA000004 respectively (considering the program counter points to the instruction being fetched, i.e. is two instruction ahead of the address when executing the branch).

      Parameters:
      address - the entry point address, in bytes
      Throws:
      IllegalArgumentException - if the given address is out of bounds, or is not word aligned, i.e. a multiple of 4

    • getValidLogo

      static byte[] getValidLogo()
      Returns the Nintendo logo expected by the console, with debugging mode disabled.
      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. The only exception are bits 2 and 7 of the 152-th byte (0x98). When both bits are set, the console's debugging mode is enabled.

      Returns:
      a copy of the logo

    • logo

      void logo​(byte[] dest)
      Copies the Nintendo logo 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, with debugging mode disabled.
      See Also:
      to get a copy of a valid logo

    • title

      String title()
      Returns the 12-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 12, or contains non-ASCII or non-uppercase characters

    • code

      String code()
      Returns the 4-character uppercase UTTD code.
      Returns:
      the UTTD code
      See Also:
      to get the cartridge type, to get the short title, to get the destination

    • setCode

      void setCode​(String code)
      Sets the UTTD code.
      Parameters:
      code - the UTTD code
      Throws:
      IllegalArgumentException - if the value has a length different from 4, or is invalid

    • type

      @Nullable GBACartridge.Type type()
      Returns the type of the cartridge, derived from the UTTD code.
      Returns:
      the cartridge type, or null if unknown

    • setType

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

    • shortTitle

      String shortTitle()
      Returns the 2-character uppercase short cartridge title, derived from the UTTD code.
      Returns:
      the short cartridge title

    • setShortTitle

      void setShortTitle​(String value)
      Sets the short cartridge title.
      Parameters:
      value - the short cartridge title
      Throws:
      IllegalArgumentException - if the value has a length different from 2, or contains non-ASCII or non-uppercase characters

    • destination

      @Nullable GBACartridge.Destination destination()
      Returns the cartridge distribution region, derived from the UTTD code.
      Returns:
      the destination, or null if unknown

    • setDestination

      void setDestination​(GBACartridge.Destination destination)
      Sets the distribution region.
      Parameters:
      destination - the destination

    • licensee

      String licensee()
      Returns the 2-character uppercase licensee code, which indicates the company or publisher of the cartridge; also known as the maker code.
      Returns:
      the licensee code

    • setLicensee

      void setLicensee​(String value)
      Sets the licensee code.
      Parameters:
      value - the licensee code
      Throws:
      IllegalArgumentException - if the value has a length different from 2, or contains non-ASCII or non-uppercase characters

    • requiredConsole

      byte requiredConsole()
      Returns the required console model to use the cartridge; also known as the main unit code.
      Returns:
      the required console model

    • setRequiredConsole

      void setRequiredConsole​(byte value)
      Sets the required console model.
      Parameters:
      value - the required console model

    • dacs

      @Nullable GBACartridge.DACSType dacs()
      Returns the type of the DACS memory, if any.
      Returns:
      the DACS memory type, or null if the debugging handler is disabled or the value is unknown

    • setDacs

      void setDacs​(GBACartridge.DACSType type)
      Enables the debugging handler and sets the given DACS memory type.
      Parameters:
      type - the DACS memory type

    • clearDacs

      void clearDacs()
      Disables the debugging handler.

    • 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