quickboot_builder.cc

/*
 * Copyright (c) 2017 Picture Elements, Inc.
 *    Stephen Williams (steve@icarus.com)
 *
 *    This source code is free software; you can redistribute it
 *    and/or modify it in source code form under the terms of the GNU
 *    General Public License as published by the Free Software
 *    Foundation; either version 2 of the License, or (at your option)
 *    any later version.
 *
 *    This program is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */

/*
 * This program reads in two .bit files, which are gold and silver
 * FPGA images, and writes them into a single .mcs file with a
 * Quickboot header as described in XAPP1081. This .mcs file is used
 * to do factory programming of the device prom. The target device can
 * then do safe updates of the silver FPGA image with some confidence
 * that the device will not be bricked if the silver image is broken.
 *
 * COMMAND LINE FLAGS:
 *   --output=<path>  Specify the output file. The resuling file will
 *                 contain the .mcs file stream.
 *
 *   --gold=<path> Specify the gold design. This should be a .bit file
 *                 as generated by Xilinx tools. Note that this .bit
 *                 file should NOT include the IPROG command as the
 *                 quickboot header that this program writes will
 *                 include a multiboot and IPROG command sequence.
 *
 *   --silver=<path>
 *                 Specify the silver design. This is the most current
 *                 design, and the design that can be updated in the
 *                 field. This file will be written to the "multiboot"
 *                 address, and the quickboot header will point to it.
 *
 *   --spi
 *   --bpi16
 *                 Specify the quickboot format, whether to write an
 *                 image for SPI flash devices or BPI devices. Exactly
 *                 one of these flags must be given.
 *
 *   --bpi16-rs0=<N> (default: 23)
 *   --bpi16-rs1=<N> (default: 24)
 *   --no-bpi16-rs0
 *   --no-bpi16-rs1
 *                 Specify how to map multiboot address bits to
 *                 RS[1:0] bits in WBSTAR.
 *
 *   --multiboot=<number>
 *                 Specify the multiboot offset. If this flag is not
 *                 present, the program will try to extract it from
 *                 the gold bit stream. If it cannot find it there,
 *                 then the program will quit with an error.
 *
 *   --disable-silver
 *   --no-disable-silver  (default)
 *                 Write the silver stream into the mcs file, but
 *                 disable it by leaving the Critical Switch word
 *                 off. Use this either to test the fallback, or to
 *                 program the device in "gold" mode and let a future
 *                 field update load and enable the silver.
 *
 *    --debug-trash-silver
 *                 Intentionally corrupt the silver image by blanking
 *                 a random sector. This is a debug aid to make sure
 *                 the fallback works. It's not intended to be used in
 *                 the real world.
 *
 * FIELD PROGRAMMING:
 * The quickboot image includes both the gold and the silver FPGA
 * images in a single MCS stream that can be written to the PROM. In
 * the field, the sinver image is meant to be updatable. The silver
 * image is in the prom at the MULTIBOOT address. To update the silver
 * image in the field, follow this process:
 *
 *   1: Erase (to 0xff) the first page/sector of the flash.
 *
 *        This disables the quickboot of the silver image, so that
 *        reboot of the flash will load the gold image. Leave the
 *        quickboot disabled until the silver image is updated.
 *
 *   2: Erase and reprogram the silver image.
 *
 *        The silver image is written to the MULTIBOOT address. Erase
 *        from there to the end of the prom, and write the new silver
 *        image in place. It is recommended that the programmer read
 *        back the entire silver image to assure that the program
 *        process worked properly.
 *
 *   3: Restore quickboot
 *
 *        Write the Critical Switch word to the last address of the
 *        first page. This re-enables the quickboot boot of the silver
 *        image.
 */


# include  "read_bit_file.h"
# include  "disable_stream_crc.h"
# include  "extract_register_write.h"
# include  "replace_register_write.h"
# include  "test_image_compat.h"
# include  "write_to_mcs_file.h"
# include  <vector>
# include  <cstdint>
# include  <cstdio>
# include  <cstdlib>
# include  <cstring>
# include  <cassert>

using namespace std;

static size_t flash_sector  = 0;

static bool disable_silver = false;

/*
 * How to map multiboot_address bits to rs[1:0] in WBSTAR.
 */
static int bpi16_rs0 = 23;
static int bpi16_rs1 = 24;

static bool test_gold_image_compatible(const std::vector<uint8_t>&vec);

static void spi_quickboot_header(std::vector<uint8_t>&dst, size_t mb_offset, size_t sector);
static void bpi16_quickboot_header(std::vector<uint8_t>&dst, size_t mb_offset, size_t sector);
static void bpi16_fixup_endian(std::vector<uint8_t>&dst);

int main(int argc, char*argv[])
{
      size_t multiboot_offset = 0;
      const char*path_out = 0;
      const char*path_gold = 0;
      const char*path_silver = 0;
      bool bpi16_gen = false;
      bool spi_gen = false;
      bool debug_trash_silver = false;

	/* Test and interpret the command line flags. */
      for (int optarg = 1 ; optarg < argc ; optarg += 1) {
	    if (strncmp(argv[optarg],"--output=",9) == 0) {
		  path_out = argv[optarg] + 9;

	    } else if (strncmp(argv[optarg],"--gold=",7) == 0) {
		  path_gold = argv[optarg] + 7;

	    } else if (strncmp(argv[optarg],"--silver=",9) == 0) {
		  path_silver = argv[optarg] + 9;

	    } else if (strcmp(argv[optarg],"--bpi16") == 0) {
		  bpi16_gen = true;

	    } else if (strcmp(argv[optarg],"--spi") == 0) {
		  spi_gen = true;

	    } else if (strncmp(argv[optarg],"--bpi16-rs0=",12) == 0) {
		  bpi16_rs0 = strtoul(argv[optarg]+12, 0, 10);

	    } else if (strncmp(argv[optarg],"--bpi16-rs1=",12) == 0) {
		  bpi16_rs1 = strtoul(argv[optarg]+12, 0, 10);

	    } else if (strcmp(argv[optarg],"--no-bpi16-rs0") == 0) {
		  bpi16_rs0 = 0;

	    } else if (strcmp(argv[optarg],"--no-bpi16-rs1") == 0) {
		  bpi16_rs1 = 0;

	    } else if (strncmp(argv[optarg],"--multiboot=",12) == 0) {
		  multiboot_offset = strtoul(argv[optarg]+12, 0, 0);

	    } else if (strcmp(argv[optarg],"--disable-silver") == 0) {
		  disable_silver = true;

	    } else if (strcmp(argv[optarg],"--no-disable-silver") == 0) {
		  disable_silver = false;

	    } else if (strcmp(argv[optarg],"--debug-trash-silver") == 0) {
		  debug_trash_silver = true;

	    } else if (strncmp(argv[optarg],"--flash-sector=",15) == 0) {
		  flash_sector = strtoul(argv[optarg]+15, 0, 0);

	    } else {
		  fprintf(stderr, "Unknown flag: %s\n", argv[optarg]);
		  return -1;
	    }
      }

      if (spi_gen==false && bpi16_gen==false) {
	    fprintf(stderr, "BPI16 or SPI? Please specify --bpi16 or --spi\n");
	    return -1;
      }

      if (spi_gen && bpi16_gen) {
	    fprintf(stderr, "Please specify only one of --bpi16 or --spi\n");
	    return -1;
      }

      if (path_out == 0) {
	    fprintf(stderr, "No output file? Please specify --output=<path>\n");
	    return -1;
      }

      if (path_silver == 0) {
	    fprintf(stderr, "No silver file file? Please specify --silver=<path>\n");
	    return -1;
      }

      if (path_gold == 0) {
	    assert(path_silver);
	    path_gold = path_silver;
	    fprintf(stderr, "No gold file, using silver file.\n");
      }


	// If the flash sector size is not otherwise specified, then
	// choose a default based on the targeted flash device.
      if (flash_sector == 0) {
	    if (spi_gen) {
		  flash_sector = 4096;
	    } else if (bpi16_gen) {
		  flash_sector = 256*1024;
	    }
      }

	// Read the gold file, strip any header, and get it ready to
	// be included in the result file.
      FILE*fd_gold = fopen(path_gold, "rb");
      if (fd_gold == 0) {
	    fprintf(stderr, "Unable to open gold file: %s\n", path_gold);
	    return -1;
      }

      fprintf(stdout, "Reading gold file: %s\n", path_gold);
      fflush(stdout);
      vector<uint8_t> vec_gold;
      read_bit_file(vec_gold, fd_gold);
      if (vec_gold.size() == 0)
	    return -1;

      fclose(fd_gold);
      fd_gold = 0;

	// If the gold file is not going to be a copy of the silver
	// file, then check that it is compatible with this process.
      if (path_gold != path_silver && !test_gold_image_compatible(vec_gold)) {
	    fprintf(stderr, "Gold file %s not compatible with Quickboot assembly.\n", path_gold);
	    return -1;
      }

	// Read the silver file, strip any header, and be ready.
      FILE*fd_silver = fopen(path_silver, "rb");
      if (fd_silver == 0) {
	    fprintf(stderr, "Unable to open silver file: %s\n", path_silver);
	    return -1;
      }

      fprintf(stdout, "Reading silver file: %s\n", path_silver);
      fflush(stdout);
      vector<uint8_t> vec_silver;
      read_bit_file(vec_silver, fd_silver);
      if (vec_silver.size() == 0)
	    return -1;

      fclose(fd_silver);
      fd_silver = 0;

      if (! test_silver_image_compatible(vec_silver)) {
	    fprintf(stderr, "Silver file %s not compatible with Quickboot assembly.\n", path_silver);
	    return -1;
      }

	/* Guess a multiboot address based on the target device we are
	   generating for. Let the command line override this guess. */
      if (multiboot_offset == 0 && bpi16_gen) {
	    multiboot_offset = 0x00800000;
      } else if (multiboot_offset == 0 && spi_gen) {
	    multiboot_offset = 0x00400000;
      }

      if (multiboot_offset == 0) {
	    fprintf(stderr, "Unable to guess the MULTIBOOT address. Please use --multiboot=<number>\n");
	    return -1;
      }

      if (multiboot_offset % flash_sector != 0) {
	    fprintf(stderr, "MULTIBOOT Address 0x%08zx is not on a prom sector boundary\n", multiboot_offset);
	    fprintf(stderr, "PROM sector size is %zu bytes\n", flash_sector);
	    return -1;
      }


      if ((vec_gold.size() + flash_sector + flash_sector) > multiboot_offset) {
	    fprintf(stderr, "Unable to fit gold bits into region.\n");
	    fprintf(stderr, "Gold file is %zu bytes\n", vec_gold.size());
	    fprintf(stderr, "MULTIBOOT byte address is 0x%08zx\n", multiboot_offset);
	    fprintf(stderr, "Quickboot header is %zu bytes\n", flash_sector + flash_sector);
	    return -1;
      }

      fprintf(stdout, "MULTIBOOT Address: 0x%08zx\n", multiboot_offset);
      fprintf(stdout, "PROM erase block Size: %zu bytes\n", flash_sector);

      const uint32_t AXSS_old = replace_register_write(vec_gold, 0x0d, 0x474f4c44);
      if (AXSS_old == 0) {
	    fprintf(stdout, "WARNING        : AXSS is not present in source stream.\n");

      } else if (AXSS_old == 0x53494c56) { // SILV
	      // Replace SILV with GOLD
	    fprintf(stdout, "... AXSS (gold): 0x474f4c44 (was: 0x%08x)\n", AXSS_old);

      } else if ((AXSS_old & 0xff000000) == 0x53000000) { // S...
	      // Replace a leading S with G
	    uint32_t AXSS_target = (AXSS_old & 0x00ffffff) | 0x47000000;
	    replace_register_write(vec_gold, 0x0d, AXSS_target);
	    fprintf(stdout, "... AXSS (gold): 0x%08x (was: 0x%08x)\n", AXSS_target, AXSS_old);
      }


      if (bpi16_gen) {
	      //uint32_t WBSTAR = replace_register_write(vec_gold, 0x10, 0x20000000);
	      //fprintf(stdout, "WBSTAR (gold): 0x20000000 (was: 0x%08x)\n", WBSTAR);

	    uint32_t COR0 = replace_register_write(vec_gold, 0x09, 0x062055dc);
	    fprintf(stdout, "COR0 (gold): 0x062055dc (was: 0x%08x)\n", COR0);

	    uint32_t COR1 = replace_register_write(vec_gold, 0x0e, 0x0000000e);
	    fprintf(stdout, "COR1 (gold): 0x0000000e (was: 0x%08x)\n", COR1);
      }

      fprintf(stdout, "Disabling CRC in gold stream (Replace CRC with Reset CRC).\n");
      while (disable_stream_crc(vec_gold)) {
	/* repeat */
      }

	// To simulate failing to program a segment of the prom, erase
	// some random sector in the silver image.
      if (debug_trash_silver) {
	    size_t trash_offset = vec_silver.size() / 2;
	    trash_offset &= ~(flash_sector-1);
	    fprintf(stdout, "**** DEBUG Trash sector at 0x%08zx in silver image.\n", trash_offset);
	    for (size_t idx = 0 ; idx < flash_sector ; idx += 1)
		  vec_silver[trash_offset+idx] = 0xff;
      }


	/* Now the vec_gold and vec_silver vectors contain the bit
	   files that will go into the quickboot assembled mcs
	   stream. */
      vector<uint8_t> vec_out;
      vec_out.resize(multiboot_offset + vec_silver.size());
      memset(&vec_out[0], 0xff, vec_out.size());

	/* Write the gold file into the stream. */
      fprintf(stdout, "Write GOLD image at byte address 0x%08zx\n",
	      flash_sector+flash_sector);
      memcpy(&vec_out[flash_sector+flash_sector], &vec_gold[0], vec_gold.size());

	/* Write the silver file into the stream. */
      fprintf(stdout, "Write SILVER image at byte address 0x%08zx\n",
	      multiboot_offset);
      memcpy(&vec_out[multiboot_offset], &vec_silver[0], vec_silver.size());

	/* Generate a quickboot header for the type of flash that we
	   are targetting. */
      assert(spi_gen || bpi16_gen);
      if (spi_gen) {
	    spi_quickboot_header(vec_out, multiboot_offset, flash_sector);

      } else if (bpi16_gen) {
	    bpi16_quickboot_header(vec_out, multiboot_offset, flash_sector);
	    bpi16_fixup_endian(vec_out);
      }

	/* Write the generated image to a .mcs file. This file can be
	   written to the prom by prom programmer. */
      FILE*fd_out = fopen(path_out, "wb");
      if (fd_out == 0) {
	    fprintf(stderr, "Unable to open output file: %s\n", path_out);
	    return -1;
      }

      write_to_mcs_file(fd_out, vec_out);

      fclose(fd_out);
      fd_out = 0;

	/* All done. */
      return 0;
}

static bool test_gold_image_compatible(const std::vector<uint8_t>&vec)
{
      if (!test_basic_image_compatibility(vec)) {
	    fprintf(stderr, "Gold image fails basic tests.\n");
	    return false;
      }

      uint32_t AXSS = extract_register_write(vec, 0x0d);
      if (AXSS != 0x474f4c44) {
	    fprintf(stderr, "Found AXSS=0x%08x\n (s/b 0x474f4c44)\n", AXSS);
	    return false;
      }

      return true;
}

static void spi_quickboot_header(std::vector<uint8_t>&dst, size_t mb_offset, size_t sector)
{
      fprintf(stdout, "Quickboot SPI header\n");
      fprintf(stdout, "Critical Switch word is aa:99:55:66 at 0x%08zx (page 0)\n", sector-4);

      memset(&dst[0], 0xff, sector-4);

      if (disable_silver) {
	    dst[sector- 4] = 0xff;
	    dst[sector- 3] = 0xff;
	    dst[sector- 2] = 0xff;
	    dst[sector- 1] = 0xff;
      } else {
	    dst[sector- 4] = 0xaa; /* Sync word */
	    dst[sector- 3] = 0x99;
	    dst[sector- 2] = 0x55;
	    dst[sector- 1] = 0x66;
      }
      dst[sector+ 0] = 0x20; /* NOOP */
      dst[sector+ 1] = 0x00;
      dst[sector+ 2] = 0x00;
      dst[sector+ 3] = 0x00;
      dst[sector+ 4] = 0x30; /* Write to WBSTAR */
      dst[sector+ 5] = 0x02;
      dst[sector+ 6] = 0x00;
      dst[sector+ 7] = 0x01;
      dst[sector+ 8] = (mb_offset>>24) & 0xff;
      dst[sector+ 9] = (mb_offset>>16) & 0xff;
      dst[sector+10] = (mb_offset>> 8) & 0xff;
      dst[sector+11] = (mb_offset>> 0) & 0xff;
      dst[sector+12] = 0x30; /* Write to COMMAND */
      dst[sector+13] = 0x00;
      dst[sector+14] = 0x80;
      dst[sector+15] = 0x01;
      dst[sector+16] = 0x00;
      dst[sector+17] = 0x00;
      dst[sector+18] = 0x00;
      dst[sector+19] = 0x0f; /* ... IPROG command */
	/* Fill the reset of the second sector with NOOP commands */
      for (size_t idx = 20 ; idx < sector ; idx += 4) {
	    dst[sector+idx+0] = 0x20;
	    dst[sector+idx+1] = 0x00;
	    dst[sector+idx+2] = 0x00;
	    dst[sector+idx+3] = 0x00;
      }
}

static void bpi16_quickboot_header(std::vector<uint8_t>&dst, size_t mb_offset, size_t sector)
{
      fprintf(stdout, "Quickboot BPI header\n");
      fprintf(stdout, "Critical Switch word is 00:00:00:bb 11:22:00:44 aa:99:44:66 at 0x%08zx (page 0)\n", sector-12);

      uint32_t WBSTAR = 0;
	// In the quickboot header for a BPI16 device, we use RS[0]
	// instead of any other multiboot bits.

	// Enable the RS pins.
      WBSTAR |= 0x20000000; /* RS_TS_B */

	// RS[0] connects to A[23] on the flash, and RS[1] to
	// A[24]. So transfer those address bits RS[] part of WBSTAR.
	// (Actually, the mapping may be more complicated then that in
	// the hardware, but this is what we do logically.)
      if ((bpi16_rs0!=0) && (mb_offset & (1 << bpi16_rs0)))
	    WBSTAR |= 0x40000000; /* RS[0]*/
      if ((bpi16_rs1!=0) && (mb_offset & (1 << bpi16_rs1)))
	    WBSTAR |= 0x80000000; /* RS[1] */

      WBSTAR |= (mb_offset & 0x00ffffff) / 2;

      fprintf(stdout, "WBSTAR (quickboot header): 0x%08x\n", WBSTAR);

      memset(&dst[0], 0xff, sector);

	// BPI16 devices don't have a simple single word that is a
	// critical sync word, so use these 3 words in the critical
	// sync flash.
      if (disable_silver) {
	      // If the silver is disabled, then leave the critical
	      // switch word out.
	    dst[sector-12] = 0xff;
	    dst[sector-11] = 0xff;
	    dst[sector-10] = 0xff;
	    dst[sector- 9] = 0xff;
	    dst[sector- 8] = 0xff;
	    dst[sector- 7] = 0xff;
	    dst[sector- 6] = 0xff;
	    dst[sector- 5] = 0xff;
	    dst[sector- 4] = 0xff;
	    dst[sector- 3] = 0xff;
	    dst[sector- 2] = 0xff;
	    dst[sector- 1] = 0xff;
      } else {
	    dst[sector-12] = 0x00; /* Critical Switch word word */
	    dst[sector-11] = 0x00;
	    dst[sector-10] = 0x00;
	    dst[sector- 9] = 0xbb;
	    dst[sector- 8] = 0x11; /* bus width detect */
	    dst[sector- 7] = 0x22;
	    dst[sector- 6] = 0x00;
	    dst[sector- 5] = 0x44;
	    dst[sector- 4] = 0xaa; /* Sync word */
	    dst[sector- 3] = 0x99;
	    dst[sector- 2] = 0x55;
	    dst[sector- 1] = 0x66;
      }
      dst[sector+ 0] = 0x20; /* NOOP */
      dst[sector+ 1] = 0x00;
      dst[sector+ 2] = 0x00;
      dst[sector+ 3] = 0x00;
      dst[sector+ 4] = 0x20; /* NOOP */
      dst[sector+ 5] = 0x00;
      dst[sector+ 6] = 0x00;
      dst[sector+ 7] = 0x00;
      dst[sector+ 8] = 0x20; /* NOOP */
      dst[sector+ 9] = 0x00;
      dst[sector+10] = 0x00;
      dst[sector+11] = 0x00;
      dst[sector+12] = 0x20; /* NOOP */
      dst[sector+13] = 0x00;
      dst[sector+14] = 0x00;
      dst[sector+15] = 0x00;
      dst[sector+16] = 0x20; /* NOOP */
      dst[sector+17] = 0x00;
      dst[sector+18] = 0x00;
      dst[sector+19] = 0x00;
      dst[sector+20] = 0x30; /* WRITE to WBSTAR */
      dst[sector+21] = 0x02;
      dst[sector+22] = 0x00;
      dst[sector+23] = 0x01;
      dst[sector+24] = (WBSTAR >> 24) & 0xff;
      dst[sector+25] = (WBSTAR >> 16) & 0xff;
      dst[sector+26] = (WBSTAR >>  8) & 0xff;
      dst[sector+27] = (WBSTAR >>  0) & 0xff;
      dst[sector+28] = 0x30; /* Write to COMMAND */
      dst[sector+29] = 0x00;
      dst[sector+30] = 0x80;
      dst[sector+31] = 0x01;
      dst[sector+32] = 0x00;
      dst[sector+33] = 0x00;
      dst[sector+34] = 0x00;
      dst[sector+35] = 0x0f; /* ... IPROG command */

	/* Fill the reset of the second sector with NOOP commands */
      for (size_t idx = 36 ; idx < sector ; idx += 4) {
	    dst[sector+idx+0] = 0x20;
	    dst[sector+idx+1] = 0x00;
	    dst[sector+idx+2] = 0x00;
	    dst[sector+idx+3] = 0x00;
      }
}

static void bpi16_fixup_endian(std::vector<uint8_t>&dst)
{
      for (size_t idx = 0 ; idx < dst.size() ; idx += 2) {
	    uint8_t tmp = dst[idx+1];
	    uint8_t val0 = tmp & 1;
	    for (int bit = 1 ; bit < 8 ; bit += 1) {
		  val0 <<= 1;
		  tmp >>= 1;
		  val0 |= tmp & 1;
	    }

	    tmp = dst[idx+0];
	    uint8_t val1 = tmp & 1;
	    for (int bit = 1 ; bit < 8 ; bit += 1) {
		  val1 <<= 1;
		  tmp >>= 1;
		  val1 |= tmp & 1;
	    }

	    dst[idx+0] = val0;
	    dst[idx+1] = val1;
      }

}