module top(
        // Input clock
        input wire CLK_12MHZ,

        // PMODs
        output wire [7:0] PMOD_C1,
        output wire [7:0] PMOD_C2
    );

    // Map those PMOD pins to some real signal names
    wire [1:0] rgb_panel_r = {PMOD_C1[4], PMOD_C1[0]};
    wire [1:0] rgb_panel_g = {PMOD_C1[5], PMOD_C1[1]};
    wire [1:0] rgb_panel_b = {PMOD_C1[6], PMOD_C1[2]};
    wire [4:0] rgb_panel_a = {PMOD_C2[7],
                              PMOD_C2[3],
                              PMOD_C2[2],
                              PMOD_C2[1],
                              PMOD_C2[0]};
    wire rgb_panel_bl = PMOD_C2[4];
    wire rgb_panel_la = PMOD_C2[5];
    wire rgb_panel_ck = PMOD_C2[6];

`default_nettype none
`define CLOCK_HZ 12_000_000
module single_colour_test(
    // Input clock to our panel driver
    input wire i_clk,
    // Shift register controls for the column data
    output reg o_data_clock,
    output reg o_data_latch,
    output reg o_data_blank,
    // Data lines to be shifted
    output reg [1:0] o_data_r,
    output reg [1:0] o_data_g,
    output reg [1:0] o_data_b,
    // Inputs to the row select demux
    output reg [4:0] o_row_select
);

    // How many pixels to shift per row
    localparam pixels_per_row = 64;

    // State machine IDs
    localparam
        s_data_shift = 0,
        s_blank_set = 1,
        s_latch_set = 2,
        s_increment_row = 3,
        s_latch_clear = 4,
        s_blank_clear = 5;

    // Simple colour cycling logic. We will have a prescaler that counts down
    // to zero twice per second, based on the frequency of our module input
    // clock (`CLOCK_HZ`).
    // Whenever this countdown hits zero, we will increment our colour state
    // register, each bit of which is mapped to the reg, green or blue data
    // channel of the RGB panel shift registers.
    localparam COLOUR_CYCLE_PRESCALER = (`CLOCK_HZ / 2) - 1;
    reg [$clog2(COLOUR_CYCLE_PRESCALER):0] colour_cycle_counter = 0;
    reg [2:0] colour_register;
    always @(posedge i_clk) begin
        if (colour_cycle_counter == 0) begin
            colour_register <= colour_register + 1;
            colour_cycle_counter <= COLOUR_CYCLE_PRESCALER;
        end else
            colour_cycle_counter <= colour_cycle_counter - 1;
    end

    // Connect the output colour data lines to our colour counter
    assign o_data_r = {colour_register[0], colour_register[0]};
    assign o_data_g = {colour_register[1], colour_register[1]};
    assign o_data_b = {colour_register[2], colour_register[2]};

    // Register to keep track of where we are in our panel update state machine
    reg [2:0] state = s_data_shift;
    // How many pixels remain to be shifted in the 'data_shift' state
    reg [7:0] pixels_to_shift = 64;
    always @(posedge i_clk) begin
        case (state)
        s_data_shift: begin // Shift out new column data for this row
            if (pixels_to_shift > 0) begin
                // We have data to shift still
                if (o_data_clock == 0) begin
                    // For this test, we have hardcoded our colour output, so
                    // there is nothing to do per-pixel here
                    o_data_clock <= 1;
                end else begin
                    o_data_clock <= 0;
                    pixels_to_shift <= pixels_to_shift - 1;
                end
            end else
               state <= s_blank_set;
         end
         // In order to update the column data, these shift registers actually
         // seem to require the output is disabled before they will latch new
         // data. So to perform an update, we have a series of steps here that
         // - Blank the output
         // - Latch the new data
         // - Increment to the new row address
         // - Reset the latch state
         // - Unblank the display.
         // Each step has been made it's own state for clarity; if one wanted
         // to save a little more on logic some of these steps can be merged.
         s_blank_set: begin o_data_blank <= 1; state <= s_latch_set; end
         s_latch_set: begin o_data_latch <= 1; state <= s_increment_row; end
         s_increment_row: begin o_row_select <= o_row_select + 1;
                                state <= s_latch_clear; end
         s_latch_clear: begin o_data_latch <= 0; state <= s_blank_clear; end
         s_blank_clear: begin
             o_data_blank <= 0;
             pixels_to_shift <= pixels_per_row;
             state <= s_data_shift;
         end
        endcase
    end
endmodule

# Resize the gif to 64x64 pixels, ignoring aspect ratio
convert -resize 64x64\! nyan_fullres.gif nyan_64.gif
# Convert the resized gif into individual frames
# This will generate nyan_frame-0.png through nyan_frame-11.png
convert -coalesce nyan_64.gif nyan_frame.png
# Now that we have our individual frames as images, we can use the img_pack
# tool to generate a binary representation of the gif to be loaded to our board
img_pack nyancat.bin nyan_frame-{0..11}.png

# To load the data into flash, we can use the faff utility to interact with the
# HX4K dev board, and write the data at offset 0x800000, safely out of the way
# of the bitstream
faff --lma 0x800000 -f nyancat.bin --no-verify
# Alternately, on an iCEBreaker, the following should work:
iceprog -o 0x800000 -X nyancat.bin

// Flash commands for use later
`define FLASH_OP_RESET    16'H6699
`define FLASH_OP_FAST_READ 8'H0B
`define FLASH_OP_WAKEUP    8'HAB

always @(posedge i_clk) begin
    case (state)
        // Default idle state. This state will only transition if the 'initiate
        // read' module input is set, at which point it will latch the base
        // address and start the read operation
        s_idle: begin
            if (i_read_stb) begin
                flash_read_addr <= i_read_addr;
                state <= s_initiate_reset;
            end
        end

        // Perform a flash chip reset. Takes advantage of our
        // flush_command_buffer state, by just specifying the data to shift,
        // and which state to transition to after the command operation is
        // complete.
        s_initiate_reset: begin
            // Our command buffer just needs the two reset bytes, the rest
            // of the bits are don't care (zero)
            command_buffer <= {`FLASH_OP_RESET, 24'b0};
            cmd_buffer_bits_to_shift <= 16;
            flash_cs <= 0;
            // Once the command is done, we want to move to the wakeup step
            next_state <= s_initiate_wakeup;
            // Directly transition to the generalized 'flush buffer' state.
            state <= s_flush_command_buffer;
        end

        // Similar to the above, but takes the flash chip out of sleep mode
        s_initiate_wakeup: begin
            command_buffer <= {`FLASH_OP_WAKEUP, 32'b0};
            // [...]
            state <= s_flush_command_buffer;
        end

        // Once again, we set up the data for flush_command_buffer, this time
        // with the 'fast read' command and the start address we latched when
        // we started the read process
        s_initiate_read: begin
            command_buffer <= {`FLASH_OP_FAST_READ, flash_read_addr, 8'b0};
            // [...]
            state <= s_flush_command_buffer;
        end

        // State for performing a command action. Shifts out a given number of
        // bits from the command buffer (MSB first), and when done transitions
        // to the state idenfitied by the next_state register.
        s_flush_command_buffer: begin
            if (cmd_buffer_bits_to_shift > 0) begin
                if (flash_sck == 0) begin
                    // Latch new data and perform rising edge
                    {flash_mosi, command_buffer} <= {command_buffer, 1'b0};
                    flash_sck <= 1;
                end else begin
                    // Perform falling edge and decrement bit count
                    flash_sck <= 0;
                    cmd_buffer_bits_to_shift <= cmd_buffer_bits_to_shift - 1;
                end
            end else begin
                // Done - move to continuation state
                state <= next_state;
                // If we aren't moving to the read state, deassert CS
                if (next_state != s_shift_data)
                    flash_cs <= 1;
            end
        end

        // Here is where we actually handle the incoming data from the flash
        // chip. Each 16 bit word is one pixel, so every time we successfully
        // read 16 bits we write it out to a block memory using the
        // ram_address, ram_data and ram_write_enable signals.
        s_shift_data: begin
            // We are going to care about 16 bit chunks, since that's
            // the interface we're using for our block RAMs
            if (words_to_read == 0) begin
                ram_write_enable <= 0;
                flash_cs <= 1;
                state <= s_idle;
            end else begin
                if (input_bits_to_shift == 0) begin
                    // Done shifting a word, move it to the output data
                    // lines and strobe the write signal
                    ram_data <= input_shift_data;
                    ram_write_enable <= 1;
                    words_to_read <= words_to_read - 1;
                    input_bits_to_shift <= 16;
                end else begin
                    // If we just did a write, bring the strobe back down
                    // and increment the write address for next time
                    if (ram_write_enable) begin
                        ram_write_enable <= 0;
                        ram_address <= ram_address + 1;
                    end
                    if (o_flash_sck == 0) begin
                        // Set up rising edge of SPI clock
                        flash_mosi <= 1'b0;
                        flash_sck <= 1;
                    end else begin
                        // Falling edge
                        flash_sck <= 0;
                        input_shift_data <= {input_shift_data[14:0], i_flash_miso};
                        input_bits_to_shift <= input_bits_to_shift - 1;
                    end
                end
            end
        end
    endcase
end

// Data to to 'read'
const uint8_t *data =
    reinterpret_cast<const uint8_t *>("This is a test string");
const unsigned data_len = strlen(data);

// Fake flash update method, should be called after each master clock cycle of
// the simulation
void DummyFlash::eval() {
  // Did the CS state change?
  if (*spi_cs != last_cs) {
    fprintf(stderr, "CS state: was %u, now %u\n", last_cs, *spi_cs);
    // If the cs line went low on this clock cycle, then the flash chip is now
    // selected. Use this as a trigger to reset our fake flash state.
    if (*spi_cs == 0) {
      shift_byte_index = 0;
      shift_bit_index = 0;
      *spi_miso = 1;
      last_sck = *spi_sck;
    } else {
      // Deselected. Move the miso line to a known state.
      *spi_miso = 1;
    }
    // Keep track of changes to the chip select pin.
    last_cs = *spi_cs;
  }

  // If we aren't selected, just return
  if (last_cs == 1) {
    return;
  }

  // Did the clock transition?
  if (*spi_sck != last_sck) {
    last_sck = *spi_sck;
    if (last_sck) {
      // Posedge, increment the number of bits we have received from the
      // SPI master
      preamble_bit_count++;
    } else {
      // Negedge
      // Don't shift data if this is the read preamble
      if (preamble_bit_count >= 40) {
        // Set miso to be the next bit
        *spi_miso =
            data[shift_byte_index % data_len] &
              (0b1000'0000 >> shift_bit_index) ? 1 : 0;
        // Increment the bit index
        shift_bit_index++;
        // If we hit the end of the byte, increment the byte index
        if (shift_bit_index > 7) {
          shift_bit_index = 0;
          shift_byte_index++;
          fprintf(stderr, "New byte: %02x\n", data[shift_byte_index]);
        }
      }
    }
  }
}

# Build the CMake project that contains the Verilator testbenches
mkdir tb/build
cd tb/build
cmake ../
make -j$(nproc)
# Run the flash loader testbench. This will generate the flash_loader.vcd file,
# which can be examined in GTKwave
./tb_flash_loader

// Animation counter for triggering frame loads from the flash chip
localparam ANIMATION_UPDATE_PRESCALER = (`clk_hz / 10) - 1; // 10fps
localparam ANIMATION_FRAME_COUNT = 11; // Number of frames in the animation
reg [$clog2(ANIMATION_UPDATE_PRESCALER):0] prescaler_reg = 0;
always @(posedge i_clk) begin
    if (prescaler_reg == 0) begin
        // Reload the prescaler downcounter register
        prescaler_reg <= ANIMATION_UPDATE_PRESCALER[$clog2(ANIMATION_UPDATE_PRESCALER):0];
        // Strobe the flash load signal
        flash_load_strobe <= 1;
        // If we have reached the final frame in the animation, go back to
        // frame 0. Otherwise, just advance to the next frame.
        if (frame_index == ANIMATION_FRAME_COUNT)
            frame_index <= 0;
        else
            frame_index <= frame_index + 1;
    end else begin
        // Downcount prescaler
        prescaler_reg <= prescaler_reg - 1;
        flash_load_strobe <= 0;
    end
end

[...]

// To connect our frame counter up to the flash reader, and knowing that each
// frame is 64*64*2 = 8192 bytes, we can create a wire that counts up the start
// address of each animation frame from a specified base address.
localparam FLASH_BASE = 24'h80_00_00;
wire [23:0] flash_load_addr = {FLASH_BASE[23:21], frame_index, 13'b0};

// On the negative edge of the serial clock cycle, set the output
// red/green/blue data. For this intermediate step, we will just set the pixel
// value to the most significant bit of that channel.
if (data_clock == 0) begin
    // We need to load the n'th most significant bit of each colour channel,
    // based on which pixel bit index we are currently displaying
    // pixel_bit_index is in range 0..4
    data_r <= {i_ram_b2_data[11 + pixel_bit_index],
               i_ram_b1_data[11 + pixel_bit_index]};
    data_g <= {i_ram_b2_data[6 + pixel_bit_index],
               i_ram_b1_data[6 + pixel_bit_index]};
    data_b <= {i_ram_b2_data[0 + pixel_bit_index],
               i_ram_b1_data[0 + pixel_bit_index]};
    data_clock <= 1;
    ram_addr <= ram_addr + 1;
end

// Our serial data output step takes 128 clock cycles (2 * the number of pixels
// in a row). So, if we enable the display of the row data for as long as it
// takes us to shift the new row of data, that's 100% duty cycle. If instead we
// cut off the display after 64 cycles, that's 50% duty, and so on.
// Here we'll create a short lookup table for how many cycles the display
// should be enabled, based on which bit of the colour information is being shown.
reg [8:0] time_periods_for_bit[5];
initial begin
    time_periods_for_bit[4] = 128;
    time_periods_for_bit[3] = 64;
    time_periods_for_bit[2] = 32;
    time_periods_for_bit[1] = 16;
    time_periods_for_bit[0] = 8;
end

// Countdown register for displaying our row data. When this hits zero, we shut
// off the output enable for the column drivers.
reg [8:0] time_periods_remaining;

// Which bit of the pixel data are we currently displaying? Counts down from
// the most significant bit (4)
reg [2:0] pixel_bit_index = 4;

// [...]

// In our data shift state, we now have one extra check to perform - decrement
// the exposure time periods, and if we hit zero, disable the output
s_data_shift: begin
    // Expose the previous row while we do our data loading.
    // Our most significant bit display time is such that it
    // matches the number of cycles it takes to load data, and then
    // each successive bit halves that value.
    if (time_periods_remaining == 0) begin
        // Turn the blanking back on
        data_blank <= 1;
    end else begin
        time_periods_remaining <= time_periods_remaining - 1;
    end

// [...]

// We also have a little logic to add to our blank_clear state -
s_blank_clear: begin
// Load the number of time periods that we should expose this
// row for
time_periods_remaining <= time_periods_for_bit[pixel_bit_index];

// If the current row address is zero, we have done one
// full scan through the display, and should move to the
// next most significant bit of colour data
if (row_address == 0) begin
   if (pixel_bit_index == 0)
       // If we hit the lsb, wrap to the msb
       pixel_bit_index <= 4;
   else
       pixel_bit_index <= pixel_bit_index - 1;
end