Reference: Interfaces¶

As described in Core Structure, cores select from and configure a variety of interfaces to interact with the hardware via the framework.

import chisel3._
import net.gamebub.framework.Core
import net.gamebub.framework.interface._

class MyCore extends Module with Core {
  val io = IO(new Bundle {
    // Hardware interfaces are declared as elements of this Bundle
  })
}

Clocks (clocks: ClocksV0)¶

Required. This interface provides the root 50 MHz clock to the core, and allows the core to provide necessary clocks to the framework (system clock, display clock, SPI clock).

The system clock, generated by the core, is the clock used with all interfaces, unless otherwise specified.

Parameters¶

• clockSystemHz: Frequency in Hz of the system clock.
• clockDisplayHz: Frequency in Hz of the LCD interface clock. Must fall within the range returned by ClocksV0.getClockDisplayHz(...).
• clockSpiHz: Frequency in Hz of the clock used to sample the MCU SPI bus. Must be at least 160 MHz.

Helpers¶

• ClocksV0.getClockDisplayHz: (Double) => (Int, Int): provides a tuple of the minimum and maximum allowable display clock frequencies (in Hz), based on the given frame period in seconds (e.g. 1.0 / 60.0).

Port Signals¶

Video (video: VideoV0)¶

Required. This interface allows the core to produce video output. The signals are referenced to the system clock.

Parameters¶

• videoWidth: Width of the active video signal (in pixels)
• videoHeight: Height of the active video signal (in pixels)
• colorDepthR: Bit-depth of the red channel
• colorDepthG: Bit-depth of the green channel
• colorDepthB: Bit-depth of the blue channel
• framePeriod: Video frame period (in seconds), e.g. 1.0 / 60.0

Port Signals¶

Host (host: HostV0)¶

Required. This interface allows the host MCU to communicate with the core. There are two main interfaces: the memory interface, and the command interface. Both interfaces use the system clock.

The memory interface is a simple memory interface (no pipelining or bursting), where a single 32-bit address is transmitted, along with a 32-bit data word read or write. enable goes high to indicate a new request is starting, with the given address, and whether it is a read (write low) or write (write high). Writes also come with dataWrite. When the core has completed the request, it must raise done. If the request was a read, dataRead must also be valid.

All memory accesses take at least two cycles: the first cycle starts when enable goes high, and the earliest it can end is on the second cycle (when done goes high). However, if the core needs additional time to handle the request, it can delay raising done until the third, fourth, or a later cycle.

The next transaction can start immediately on the cycle after done goes high.

Addresses beginning with 0xFxxxxxxx are reserved for use by the framework. Except as explicitly specified (e.g. for the command interface), the core must not map its own registers or memory at these addresses.

There are two command interfaces: commandHost (for Host -> Core commands), and commandCore (for Core -> Host) commands. Each provides a separate request / response channel.

The command interfaces are described in a later section.

Port Signals¶

Audio (audio: AudioV0)¶

Optional. This interface allows the core to produce audio output. The signals are referenced to the system clock.

The sample rate is always 48000 Hz, so the core should update left and right at 48 kHz.

Port Signals¶

Input (input: InputV0)¶

Optional. This interface allows the core to receive button input. Each button signal is active-high and synchronized into the system clock domain.

Port Signals¶

Vibrate (vibrate: VibrateV0)¶

Optional. This interface allows the core to produce haptic feedback (vibration).

The mode can be either:

• Off (0b00)
• On (0b01)
• Brake (0b10)

Port Signals¶

Cartridge Port (cartridge: CartridgePortV0)¶

Optional. This interface allows the core to access the cartridge slot. Note that cartridge power must be enabled in the core.json metadata file.

Cartridge pins go through level shifters, and the I/O voltage is controlled automatically by the hardware based on a shape-detecting switch in the cartridge slot.

For each direction signal, high (1) indicates output from FPGA to cartridge, 0 indicates input from cartridge to FPGA.

Port Signals¶

Link Port (link: LinkPortV0)¶

Optional. This interface allows the core to access the link port. The voltage is automatically controlled by the cartridge shape-detector switch.

For each direction signal, high (1) indicates output, 0 indicates input.

Port Signals¶

PMOD (pmod: PmodV0)¶

Optional. This interface allows the core to access the PMOD connector at the top of the device. All I/Os are 3.3 V and unbuffered.

For each direction signal, high (1) indicates output, 0 indicates input.

Port Signals¶

SDRAM (sdram: SdramV0)¶

Optional. This interface allows the core to access SDRAM memory chips.

For each direction signal, high (1) indicates output, 0 indicates input.

Game Bub Rev4 has 2x 32 MiB SDRAM chips with a 16-bit data bus.

Parameters¶

• addressWidth: Row/column address bus width (default: 13)
• dataWidth: Data bus width (default: 16)
• bankWidth: Bank addres width (default: 2)
• chips: Number of parallel chips / chip-select lines (default: 1)

Helpers¶

• SdramV0.numChips: Int: exposes the number of SDRAM chips available on the target

Port Signals¶

SRAM (sram: SramV0)¶

Optional. This interface allows the core to access asynchronous SRAM memory chips.

For each direction signal, high (1) indicates output, 0 indicates input.

Game Bub Rev4 has a 512 KiB, 16-bit data bus asynchronous SRAM chip.

Parameters¶

• addressWidth: Address bus width (default: 18)
• dataWidth: Data bus width (default: 16)

Port Signals¶

Video Filter (videoFilter: VideoFilterBasicV0)¶

Optional. This interface allows the core to apply filter effects to video output after scaling.

These signals are in the display clock domain, not the system clock domain.

Parameters¶

• colorInDepthR: Bit-depth of the red channel (must match video)
• colorInDepthG: Bit-depth of the green channel (must match video)
• colorInDepthB: Bit-depth of the blue channel (must match video)
• latency: Latency from filter input to output (in clock cycles)

Port Signals¶

Host/Core Commands¶

To begin a request, the initiator raises request high, and holds it high for the duration of the request. The receiver then raises the busy signal, to indicate it is working on the request. When the receiver is finished, it raises the done signal (and the error signal, if the command completed in an error).

After the initiator is done handling the response, they must lower request. Then, they may raise request again to send a new request, and the whole process repeats.

Parameters and Results¶

Request parameters and results are transmitted using the memory bus, in the regions 0xF000_0000 (Host -> Core) and 0xF000_1000 (Core -> Host). Each parameter and result is 32 bits.

Before raising request, the host writes its command opcode to 0xF000_0000, its first parameter (if there is one) to 0xF000_0004, its second parameter (if there is one) to 0xF000_0008, etc.

Upon request completion (when done goes high), the host will read the first result word from 0xF000_0000, the second result word from 0xF000_0004, etc.

For Core -> Host commands, the same interface holds true, but in reverse, at starting at 0xF000_1000. That is, when request is raised by the core, the host will read the opcode from 0xF000_1000, the first parameter from 0xF000_1004, etc. And similarly, before it raises done, it will write the first result word to 0xF000_1000, the second to 0xF000_1004, etc.

Host -> Core commands¶

GetStatus (0x0000)¶

Called by the host to request the status of the core. No parameters. The result is a single value, indicating the status:

• StatusUnknown = 0: unknown status
• StatusInitialize = 1: the core is initializing itself
• StatusSetup = 2: the core has initialized, and is ready for the host to transmit commands and memory accesses
• StatusCoreHalt = 3: the core has been set up, and is halted in reset
• StatusCoreRun = 4: the core is actively running

CoreRun (0x0100)¶

Called by the host to start core execution (taking it out of reset).

No parameters or results.

The core should transition to StatusCoreRun.

CoreHalt (0x0101)¶

Called by the host to halt core execution (putting it into reset).

No parameters or results.

The core should transition to StatusCoreHalt.

SetupComplete (0x0102)¶

Called by the host to indicate that it is done setting up the core (files and settings have been transmitted).

No parameters or results.

The core should finalize its setup and transition to StatusCoreHalt.

NotifyFocus (0x0200)¶

Called by the host to indicate that the core gained or lost UI focus. When not focused, video may be obscured by a menu, audio may be silenced, and the core will not receive any input.

The core may choose to (but does not have to) pause itself.

One parameter: 1 if the core has gained focus, 0 if the core has lost focus. No results.

FileWriteStart (0x0300)¶

Called by the host before it starts writing a file to the core via the host memory interface.

One parameter: the file ID, defined in files.json. No results.

FileWriteEnd (0x0301)¶

Called by the host when it has finished writing the file.

Three parameters: 1. The file ID 2. The total size of the file transferred, in bytes 3. Reserved (0)

No results.

FileReadStart (0x0302)¶

Called by the host before it starts reading a file from the core via the host memory interface.

One parameter: the file ID. One result: the file size in bytes.

FileReadEnd (0x0303)¶

Called by the host when it has finished reading the file.

One parameter: the file ID. No results.

Core -> Host commands¶

There are no core initiated commands yet.