Add libusb and libuvc
[rtmpclient.git] / app / src / main / jni / libusb-1.0.22 / examples / ezusb.c
diff --git a/app/src/main/jni/libusb-1.0.22/examples/ezusb.c b/app/src/main/jni/libusb-1.0.22/examples/ezusb.c
new file mode 100644 (file)
index 0000000..e3b488d
--- /dev/null
@@ -0,0 +1,831 @@
+/*
+ * Copyright © 2001 Stephen Williams (steve@icarus.com)
+ * Copyright © 2001-2002 David Brownell (dbrownell@users.sourceforge.net)
+ * Copyright © 2008 Roger Williams (rawqux@users.sourceforge.net)
+ * Copyright © 2012 Pete Batard (pete@akeo.ie)
+ * Copyright © 2013 Federico Manzan (f.manzan@gmail.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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+ */
+#include <stdio.h>
+#include <errno.h>
+#include <stdlib.h>
+#include <string.h>
+#include <stdint.h>
+
+#include "libusb.h"
+#include "ezusb.h"
+
+extern void logerror(const char *format, ...)
+       __attribute__ ((format(printf, 1, 2)));
+
+/*
+ * This file contains functions for uploading firmware into Cypress
+ * EZ-USB microcontrollers. These chips use control endpoint 0 and vendor
+ * specific commands to support writing into the on-chip SRAM. They also
+ * support writing into the CPUCS register, which is how we reset the
+ * processor after loading firmware (including the reset vector).
+ *
+ * These Cypress devices are 8-bit 8051 based microcontrollers with
+ * special support for USB I/O.  They come in several packages, and
+ * some can be set up with external memory when device costs allow.
+ * Note that the design was originally by AnchorChips, so you may find
+ * references to that vendor (which was later merged into Cypress).
+ * The Cypress FX parts are largely compatible with the Anchorhip ones.
+ */
+
+int verbose = 1;
+
+/*
+ * return true if [addr,addr+len] includes external RAM
+ * for Anchorchips EZ-USB or Cypress EZ-USB FX
+ */
+static bool fx_is_external(uint32_t addr, size_t len)
+{
+       /* with 8KB RAM, 0x0000-0x1b3f can be written
+        * we can't tell if it's a 4KB device here
+        */
+       if (addr <= 0x1b3f)
+               return ((addr + len) > 0x1b40);
+
+       /* there may be more RAM; unclear if we can write it.
+        * some bulk buffers may be unused, 0x1b3f-0x1f3f
+        * firmware can set ISODISAB for 2KB at 0x2000-0x27ff
+        */
+       return true;
+}
+
+/*
+ * return true if [addr,addr+len] includes external RAM
+ * for Cypress EZ-USB FX2
+ */
+static bool fx2_is_external(uint32_t addr, size_t len)
+{
+       /* 1st 8KB for data/code, 0x0000-0x1fff */
+       if (addr <= 0x1fff)
+               return ((addr + len) > 0x2000);
+
+       /* and 512 for data, 0xe000-0xe1ff */
+       else if (addr >= 0xe000 && addr <= 0xe1ff)
+               return ((addr + len) > 0xe200);
+
+       /* otherwise, it's certainly external */
+       else
+               return true;
+}
+
+/*
+ * return true if [addr,addr+len] includes external RAM
+ * for Cypress EZ-USB FX2LP
+ */
+static bool fx2lp_is_external(uint32_t addr, size_t len)
+{
+       /* 1st 16KB for data/code, 0x0000-0x3fff */
+       if (addr <= 0x3fff)
+               return ((addr + len) > 0x4000);
+
+       /* and 512 for data, 0xe000-0xe1ff */
+       else if (addr >= 0xe000 && addr <= 0xe1ff)
+               return ((addr + len) > 0xe200);
+
+       /* otherwise, it's certainly external */
+       else
+               return true;
+}
+
+
+/*****************************************************************************/
+
+/*
+ * These are the requests (bRequest) that the bootstrap loader is expected
+ * to recognize.  The codes are reserved by Cypress, and these values match
+ * what EZ-USB hardware, or "Vend_Ax" firmware (2nd stage loader) uses.
+ * Cypress' "a3load" is nice because it supports both FX and FX2, although
+ * it doesn't have the EEPROM support (subset of "Vend_Ax").
+ */
+#define RW_INTERNAL     0xA0   /* hardware implements this one */
+#define RW_MEMORY       0xA3
+
+/*
+ * Issues the specified vendor-specific write request.
+ */
+static int ezusb_write(libusb_device_handle *device, const char *label,
+       uint8_t opcode, uint32_t addr, const unsigned char *data, size_t len)
+{
+       int status;
+
+       if (verbose > 1)
+               logerror("%s, addr 0x%08x len %4u (0x%04x)\n", label, addr, (unsigned)len, (unsigned)len);
+       status = libusb_control_transfer(device,
+               LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_VENDOR | LIBUSB_RECIPIENT_DEVICE,
+               opcode, addr & 0xFFFF, addr >> 16,
+               (unsigned char*)data, (uint16_t)len, 1000);
+       if (status != (signed)len) {
+               if (status < 0)
+                       logerror("%s: %s\n", label, libusb_error_name(status));
+               else
+                       logerror("%s ==> %d\n", label, status);
+       }
+       return (status < 0) ? -EIO : 0;
+}
+
+/*
+ * Issues the specified vendor-specific read request.
+ */
+static int ezusb_read(libusb_device_handle *device, const char *label,
+       uint8_t opcode, uint32_t addr, const unsigned char *data, size_t len)
+{
+       int status;
+
+       if (verbose > 1)
+               logerror("%s, addr 0x%08x len %4u (0x%04x)\n", label, addr, (unsigned)len, (unsigned)len);
+       status = libusb_control_transfer(device,
+               LIBUSB_ENDPOINT_IN | LIBUSB_REQUEST_TYPE_VENDOR | LIBUSB_RECIPIENT_DEVICE,
+               opcode, addr & 0xFFFF, addr >> 16,
+               (unsigned char*)data, (uint16_t)len, 1000);
+       if (status != (signed)len) {
+               if (status < 0)
+                       logerror("%s: %s\n", label, libusb_error_name(status));
+               else
+                       logerror("%s ==> %d\n", label, status);
+       }
+       return (status < 0) ? -EIO : 0;
+}
+
+/*
+ * Modifies the CPUCS register to stop or reset the CPU.
+ * Returns false on error.
+ */
+static bool ezusb_cpucs(libusb_device_handle *device, uint32_t addr, bool doRun)
+{
+       int status;
+       uint8_t data = doRun ? 0x00 : 0x01;
+
+       if (verbose)
+               logerror("%s\n", data ? "stop CPU" : "reset CPU");
+       status = libusb_control_transfer(device,
+               LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_VENDOR | LIBUSB_RECIPIENT_DEVICE,
+               RW_INTERNAL, addr & 0xFFFF, addr >> 16,
+               &data, 1, 1000);
+       if ((status != 1) &&
+               /* We may get an I/O error from libusb as the device disappears */
+               ((!doRun) || (status != LIBUSB_ERROR_IO)))
+       {
+               const char *mesg = "can't modify CPUCS";
+               if (status < 0)
+                       logerror("%s: %s\n", mesg, libusb_error_name(status));
+               else
+                       logerror("%s\n", mesg);
+               return false;
+       } else
+               return true;
+}
+
+/*
+ * Send an FX3 jumpt to address command
+ * Returns false on error.
+ */
+static bool ezusb_fx3_jump(libusb_device_handle *device, uint32_t addr)
+{
+       int status;
+
+       if (verbose)
+               logerror("transfer execution to Program Entry at 0x%08x\n", addr);
+       status = libusb_control_transfer(device,
+               LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_VENDOR | LIBUSB_RECIPIENT_DEVICE,
+               RW_INTERNAL, addr & 0xFFFF, addr >> 16,
+               NULL, 0, 1000);
+       /* We may get an I/O error from libusb as the device disappears */
+       if ((status != 0) && (status != LIBUSB_ERROR_IO))
+       {
+               const char *mesg = "failed to send jump command";
+               if (status < 0)
+                       logerror("%s: %s\n", mesg, libusb_error_name(status));
+               else
+                       logerror("%s\n", mesg);
+               return false;
+       } else
+               return true;
+}
+
+/*****************************************************************************/
+
+/*
+ * Parse an Intel HEX image file and invoke the poke() function on the
+ * various segments to implement policies such as writing to RAM (with
+ * a one or two stage loader setup, depending on the firmware) or to
+ * EEPROM (two stages required).
+ *
+ * image       - the hex image file
+ * context     - for use by poke()
+ * is_external - if non-null, used to check which segments go into
+ *               external memory (writable only by software loader)
+ * poke        - called with each memory segment; errors indicated
+ *               by returning negative values.
+ *
+ * Caller is responsible for halting CPU as needed, such as when
+ * overwriting a second stage loader.
+ */
+static int parse_ihex(FILE *image, void *context,
+       bool (*is_external)(uint32_t addr, size_t len),
+       int (*poke) (void *context, uint32_t addr, bool external,
+       const unsigned char *data, size_t len))
+{
+       unsigned char data[1023];
+       uint32_t data_addr = 0;
+       size_t data_len = 0;
+       int rc;
+       int first_line = 1;
+       bool external = false;
+
+       /* Read the input file as an IHEX file, and report the memory segments
+        * as we go.  Each line holds a max of 16 bytes, but uploading is
+        * faster (and EEPROM space smaller) if we merge those lines into larger
+        * chunks.  Most hex files keep memory segments together, which makes
+        * such merging all but free.  (But it may still be worth sorting the
+        * hex files to make up for undesirable behavior from tools.)
+        *
+        * Note that EEPROM segments max out at 1023 bytes; the upload protocol
+        * allows segments of up to 64 KBytes (more than a loader could handle).
+        */
+       for (;;) {
+               char buf[512], *cp;
+               char tmp, type;
+               size_t len;
+               unsigned idx, off;
+
+               cp = fgets(buf, sizeof(buf), image);
+               if (cp == NULL) {
+                       logerror("EOF without EOF record!\n");
+                       break;
+               }
+
+               /* EXTENSION: "# comment-till-end-of-line", for copyrights etc */
+               if (buf[0] == '#')
+                       continue;
+
+               if (buf[0] != ':') {
+                       logerror("not an ihex record: %s", buf);
+                       return -2;
+               }
+
+               /* ignore any newline */
+               cp = strchr(buf, '\n');
+               if (cp)
+                       *cp = 0;
+
+               if (verbose >= 3)
+                       logerror("** LINE: %s\n", buf);
+
+               /* Read the length field (up to 16 bytes) */
+               tmp = buf[3];
+               buf[3] = 0;
+               len = strtoul(buf+1, NULL, 16);
+               buf[3] = tmp;
+
+               /* Read the target offset (address up to 64KB) */
+               tmp = buf[7];
+               buf[7] = 0;
+               off = (int)strtoul(buf+3, NULL, 16);
+               buf[7] = tmp;
+
+               /* Initialize data_addr */
+               if (first_line) {
+                       data_addr = off;
+                       first_line = 0;
+               }
+
+               /* Read the record type */
+               tmp = buf[9];
+               buf[9] = 0;
+               type = (char)strtoul(buf+7, NULL, 16);
+               buf[9] = tmp;
+
+               /* If this is an EOF record, then make it so. */
+               if (type == 1) {
+                       if (verbose >= 2)
+                               logerror("EOF on hexfile\n");
+                       break;
+               }
+
+               if (type != 0) {
+                       logerror("unsupported record type: %u\n", type);
+                       return -3;
+               }
+
+               if ((len * 2) + 11 > strlen(buf)) {
+                       logerror("record too short?\n");
+                       return -4;
+               }
+
+               /* FIXME check for _physically_ contiguous not just virtually
+                * e.g. on FX2 0x1f00-0x2100 includes both on-chip and external
+                * memory so it's not really contiguous */
+
+               /* flush the saved data if it's not contiguous,
+               * or when we've buffered as much as we can.
+               */
+               if (data_len != 0
+                       && (off != (data_addr + data_len)
+                       /* || !merge */
+                       || (data_len + len) > sizeof(data))) {
+                               if (is_external)
+                                       external = is_external(data_addr, data_len);
+                               rc = poke(context, data_addr, external, data, data_len);
+                               if (rc < 0)
+                                       return -1;
+                               data_addr = off;
+                               data_len = 0;
+               }
+
+               /* append to saved data, flush later */
+               for (idx = 0, cp = buf+9 ;  idx < len ;  idx += 1, cp += 2) {
+                       tmp = cp[2];
+                       cp[2] = 0;
+                       data[data_len + idx] = (uint8_t)strtoul(cp, NULL, 16);
+                       cp[2] = tmp;
+               }
+               data_len += len;
+       }
+
+
+       /* flush any data remaining */
+       if (data_len != 0) {
+               if (is_external)
+                       external = is_external(data_addr, data_len);
+               rc = poke(context, data_addr, external, data, data_len);
+               if (rc < 0)
+                       return -1;
+       }
+       return 0;
+}
+
+/*
+ * Parse a binary image file and write it as is to the target.
+ * Applies to Cypress BIX images for RAM or Cypress IIC images
+ * for EEPROM.
+ *
+ * image       - the BIX image file
+ * context     - for use by poke()
+ * is_external - if non-null, used to check which segments go into
+ *               external memory (writable only by software loader)
+ * poke        - called with each memory segment; errors indicated
+ *               by returning negative values.
+ *
+ * Caller is responsible for halting CPU as needed, such as when
+ * overwriting a second stage loader.
+ */
+static int parse_bin(FILE *image, void *context,
+       bool (*is_external)(uint32_t addr, size_t len), int (*poke)(void *context,
+       uint32_t addr, bool external, const unsigned char *data, size_t len))
+{
+       unsigned char data[4096];
+       uint32_t data_addr = 0;
+       size_t data_len = 0;
+       int rc;
+       bool external = false;
+
+       for (;;) {
+               data_len = fread(data, 1, 4096, image);
+               if (data_len == 0)
+                       break;
+               if (is_external)
+                       external = is_external(data_addr, data_len);
+               rc = poke(context, data_addr, external, data, data_len);
+               if (rc < 0)
+                       return -1;
+               data_addr += (uint32_t)data_len;
+       }
+       return feof(image)?0:-1;
+}
+
+/*
+ * Parse a Cypress IIC image file and invoke the poke() function on the
+ * various segments for writing to RAM
+ *
+ * image       - the IIC image file
+ * context     - for use by poke()
+ * is_external - if non-null, used to check which segments go into
+ *               external memory (writable only by software loader)
+ * poke        - called with each memory segment; errors indicated
+ *               by returning negative values.
+ *
+ * Caller is responsible for halting CPU as needed, such as when
+ * overwriting a second stage loader.
+ */
+static int parse_iic(FILE *image, void *context,
+       bool (*is_external)(uint32_t addr, size_t len),
+       int (*poke)(void *context, uint32_t addr, bool external, const unsigned char *data, size_t len))
+{
+       unsigned char data[4096];
+       uint32_t data_addr = 0;
+       size_t data_len = 0, read_len;
+       uint8_t block_header[4];
+       int rc;
+       bool external = false;
+       long file_size, initial_pos;
+
+       initial_pos = ftell(image);
+       if (initial_pos < 0)
+               return -1;
+
+       if (fseek(image, 0L, SEEK_END) != 0)
+               return -1;
+       file_size = ftell(image);
+       if (fseek(image, initial_pos, SEEK_SET) != 0)
+               return -1;
+       for (;;) {
+               /* Ignore the trailing reset IIC data (5 bytes) */
+               if (ftell(image) >= (file_size - 5))
+                       break;
+               if (fread(&block_header, 1, sizeof(block_header), image) != 4) {
+                       logerror("unable to read IIC block header\n");
+                       return -1;
+               }
+               data_len = (block_header[0] << 8) + block_header[1];
+               data_addr = (block_header[2] << 8) + block_header[3];
+               if (data_len > sizeof(data)) {
+                       /* If this is ever reported as an error, switch to using malloc/realloc */
+                       logerror("IIC data block too small - please report this error to libusb.info\n");
+                       return -1;
+               }
+               read_len = fread(data, 1, data_len, image);
+               if (read_len != data_len) {
+                       logerror("read error\n");
+                       return -1;
+               }
+               if (is_external)
+                       external = is_external(data_addr, data_len);
+               rc = poke(context, data_addr, external, data, data_len);
+               if (rc < 0)
+                       return -1;
+       }
+       return 0;
+}
+
+/* the parse call will be selected according to the image type */
+static int (*parse[IMG_TYPE_MAX])(FILE *image, void *context, bool (*is_external)(uint32_t addr, size_t len),
+           int (*poke)(void *context, uint32_t addr, bool external, const unsigned char *data, size_t len))
+           = { parse_ihex, parse_iic, parse_bin };
+
+/*****************************************************************************/
+
+/*
+ * For writing to RAM using a first (hardware) or second (software)
+ * stage loader and 0xA0 or 0xA3 vendor requests
+ */
+typedef enum {
+       _undef = 0,
+       internal_only,          /* hardware first-stage loader */
+       skip_internal,          /* first phase, second-stage loader */
+       skip_external           /* second phase, second-stage loader */
+} ram_mode;
+
+struct ram_poke_context {
+       libusb_device_handle *device;
+       ram_mode mode;
+       size_t total, count;
+};
+
+#define RETRY_LIMIT 5
+
+static int ram_poke(void *context, uint32_t addr, bool external,
+       const unsigned char *data, size_t len)
+{
+       struct ram_poke_context *ctx = (struct ram_poke_context*)context;
+       int rc;
+       unsigned retry = 0;
+
+       switch (ctx->mode) {
+       case internal_only:             /* CPU should be stopped */
+               if (external) {
+                       logerror("can't write %u bytes external memory at 0x%08x\n",
+                               (unsigned)len, addr);
+                       return -EINVAL;
+               }
+               break;
+       case skip_internal:             /* CPU must be running */
+               if (!external) {
+                       if (verbose >= 2) {
+                               logerror("SKIP on-chip RAM, %u bytes at 0x%08x\n",
+                                       (unsigned)len, addr);
+                       }
+                       return 0;
+               }
+               break;
+       case skip_external:             /* CPU should be stopped */
+               if (external) {
+                       if (verbose >= 2) {
+                               logerror("SKIP external RAM, %u bytes at 0x%08x\n",
+                                       (unsigned)len, addr);
+                       }
+                       return 0;
+               }
+               break;
+       case _undef:
+       default:
+               logerror("bug\n");
+               return -EDOM;
+       }
+
+       ctx->total += len;
+       ctx->count++;
+
+       /* Retry this till we get a real error. Control messages are not
+        * NAKed (just dropped) so time out means is a real problem.
+        */
+       while ((rc = ezusb_write(ctx->device,
+               external ? "write external" : "write on-chip",
+               external ? RW_MEMORY : RW_INTERNAL,
+               addr, data, len)) < 0
+               && retry < RETRY_LIMIT) {
+               if (rc != LIBUSB_ERROR_TIMEOUT)
+                       break;
+               retry += 1;
+       }
+       return rc;
+}
+
+/*
+ * Load a Cypress Image file into target RAM.
+ * See http://www.cypress.com/?docID=41351 (AN76405 PDF) for more info.
+ */
+static int fx3_load_ram(libusb_device_handle *device, const char *path)
+{
+       uint32_t dCheckSum, dExpectedCheckSum, dAddress, i, dLen, dLength;
+       uint32_t* dImageBuf;
+       unsigned char *bBuf, hBuf[4], blBuf[4], rBuf[4096];
+       FILE *image;
+       int ret = 0;
+
+       image = fopen(path, "rb");
+       if (image == NULL) {
+               logerror("unable to open '%s' for input\n", path);
+               return -2;
+       } else if (verbose)
+               logerror("open firmware image %s for RAM upload\n", path);
+
+       // Read header
+       if (fread(hBuf, sizeof(char), sizeof(hBuf), image) != sizeof(hBuf)) {
+               logerror("could not read image header");
+               ret = -3;
+               goto exit;
+       }
+
+       // check "CY" signature byte and format
+       if ((hBuf[0] != 'C') || (hBuf[1] != 'Y')) {
+               logerror("image doesn't have a CYpress signature\n");
+               ret = -3;
+               goto exit;
+       }
+
+       // Check bImageType
+       switch(hBuf[3]) {
+       case 0xB0:
+               if (verbose)
+                       logerror("normal FW binary %s image with checksum\n", (hBuf[2]&0x01)?"data":"executable");
+               break;
+       case 0xB1:
+               logerror("security binary image is not currently supported\n");
+               ret = -3;
+               goto exit;
+       case 0xB2:
+               logerror("VID:PID image is not currently supported\n");
+               ret = -3;
+               goto exit;
+       default:
+               logerror("invalid image type 0x%02X\n", hBuf[3]);
+               ret = -3;
+               goto exit;
+       }
+
+       // Read the bootloader version
+       if (verbose) {
+               if ((ezusb_read(device, "read bootloader version", RW_INTERNAL, 0xFFFF0020, blBuf, 4) < 0)) {
+                       logerror("Could not read bootloader version\n");
+                       ret = -8;
+                       goto exit;
+               }
+               logerror("FX3 bootloader version: 0x%02X%02X%02X%02X\n", blBuf[3], blBuf[2], blBuf[1], blBuf[0]);
+       }
+
+       dCheckSum = 0;
+       if (verbose)
+               logerror("writing image...\n");
+       while (1) {
+               if ((fread(&dLength, sizeof(uint32_t), 1, image) != 1) ||  // read dLength
+                       (fread(&dAddress, sizeof(uint32_t), 1, image) != 1)) { // read dAddress
+                       logerror("could not read image");
+                       ret = -3;
+                       goto exit;
+               }
+               if (dLength == 0)
+                       break; // done
+
+               // coverity[tainted_data]
+               dImageBuf = (uint32_t*)calloc(dLength, sizeof(uint32_t));
+               if (dImageBuf == NULL) {
+                       logerror("could not allocate buffer for image chunk\n");
+                       ret = -4;
+                       goto exit;
+               }
+
+               // read sections
+               if (fread(dImageBuf, sizeof(uint32_t), dLength, image) != dLength) {
+                       logerror("could not read image");
+                       free(dImageBuf);
+                       ret = -3;
+                       goto exit;
+               }
+               for (i = 0; i < dLength; i++)
+                       dCheckSum += dImageBuf[i];
+               dLength <<= 2; // convert to Byte length
+               bBuf = (unsigned char*) dImageBuf;
+
+               while (dLength > 0) {
+                       dLen = 4096; // 4K max
+                       if (dLen > dLength)
+                               dLen = dLength;
+                       if ((ezusb_write(device, "write firmware", RW_INTERNAL, dAddress, bBuf, dLen) < 0) ||
+                               (ezusb_read(device, "read firmware", RW_INTERNAL, dAddress, rBuf, dLen) < 0)) {
+                               logerror("R/W error\n");
+                               free(dImageBuf);
+                               ret = -5;
+                               goto exit;
+                       }
+                       // Verify data: rBuf with bBuf
+                       for (i = 0; i < dLen; i++) {
+                               if (rBuf[i] != bBuf[i]) {
+                                       logerror("verify error");
+                                       free(dImageBuf);
+                                       ret = -6;
+                                       goto exit;
+                               }
+                       }
+
+                       dLength -= dLen;
+                       bBuf += dLen;
+                       dAddress += dLen;
+               }
+               free(dImageBuf);
+       }
+
+       // read pre-computed checksum data
+       if ((fread(&dExpectedCheckSum, sizeof(uint32_t), 1, image) != 1) ||
+               (dCheckSum != dExpectedCheckSum)) {
+               logerror("checksum error\n");
+               ret = -7;
+               goto exit;
+       }
+
+       // transfer execution to Program Entry
+       if (!ezusb_fx3_jump(device, dAddress)) {
+               ret = -6;
+       }
+
+exit:
+       fclose(image);
+       return ret;
+}
+
+/*
+ * Load a firmware file into target RAM. device is the open libusb
+ * device, and the path is the name of the source file. Open the file,
+ * parse the bytes, and write them in one or two phases.
+ *
+ * If stage == 0, this uses the first stage loader, built into EZ-USB
+ * hardware but limited to writing on-chip memory or CPUCS.  Everything
+ * is written during one stage, unless there's an error such as the image
+ * holding data that needs to be written to external memory.
+ *
+ * Otherwise, things are written in two stages.  First the external
+ * memory is written, expecting a second stage loader to have already
+ * been loaded.  Then file is re-parsed and on-chip memory is written.
+ */
+int ezusb_load_ram(libusb_device_handle *device, const char *path, int fx_type, int img_type, int stage)
+{
+       FILE *image;
+       uint32_t cpucs_addr;
+       bool (*is_external)(uint32_t off, size_t len);
+       struct ram_poke_context ctx;
+       int status;
+       uint8_t iic_header[8] = { 0 };
+       int ret = 0;
+
+       if (fx_type == FX_TYPE_FX3)
+               return fx3_load_ram(device, path);
+
+       image = fopen(path, "rb");
+       if (image == NULL) {
+               logerror("%s: unable to open for input.\n", path);
+               return -2;
+       } else if (verbose > 1)
+               logerror("open firmware image %s for RAM upload\n", path);
+
+       if (img_type == IMG_TYPE_IIC) {
+               if ( (fread(iic_header, 1, sizeof(iic_header), image) != sizeof(iic_header))
+                 || (((fx_type == FX_TYPE_FX2LP) || (fx_type == FX_TYPE_FX2)) && (iic_header[0] != 0xC2))
+                 || ((fx_type == FX_TYPE_AN21) && (iic_header[0] != 0xB2))
+                 || ((fx_type == FX_TYPE_FX1) && (iic_header[0] != 0xB6)) ) {
+                       logerror("IIC image does not contain executable code - cannot load to RAM.\n");
+                       ret = -1;
+                       goto exit;
+               }
+       }
+
+       /* EZ-USB original/FX and FX2 devices differ, apart from the 8051 core */
+       switch(fx_type) {
+       case FX_TYPE_FX2LP:
+               cpucs_addr = 0xe600;
+               is_external = fx2lp_is_external;
+               break;
+       case FX_TYPE_FX2:
+               cpucs_addr = 0xe600;
+               is_external = fx2_is_external;
+               break;
+       default:
+               cpucs_addr = 0x7f92;
+               is_external = fx_is_external;
+               break;
+       }
+
+       /* use only first stage loader? */
+       if (stage == 0) {
+               ctx.mode = internal_only;
+
+               /* if required, halt the CPU while we overwrite its code/data */
+               if (cpucs_addr && !ezusb_cpucs(device, cpucs_addr, false))
+               {
+                       ret = -1;
+                       goto exit;
+               }
+
+               /* 2nd stage, first part? loader was already uploaded */
+       } else {
+               ctx.mode = skip_internal;
+
+               /* let CPU run; overwrite the 2nd stage loader later */
+               if (verbose)
+                       logerror("2nd stage: write external memory\n");
+       }
+
+       /* scan the image, first (maybe only) time */
+       ctx.device = device;
+       ctx.total = ctx.count = 0;
+       status = parse[img_type](image, &ctx, is_external, ram_poke);
+       if (status < 0) {
+               logerror("unable to upload %s\n", path);
+               ret = status;
+               goto exit;
+       }
+
+       /* second part of 2nd stage: rescan */
+       // TODO: what should we do for non HEX images there?
+       if (stage) {
+               ctx.mode = skip_external;
+
+               /* if needed, halt the CPU while we overwrite the 1st stage loader */
+               if (cpucs_addr && !ezusb_cpucs(device, cpucs_addr, false))
+               {
+                       ret = -1;
+                       goto exit;
+               }
+
+               /* at least write the interrupt vectors (at 0x0000) for reset! */
+               rewind(image);
+               if (verbose)
+                       logerror("2nd stage: write on-chip memory\n");
+               status = parse_ihex(image, &ctx, is_external, ram_poke);
+               if (status < 0) {
+                       logerror("unable to completely upload %s\n", path);
+                       ret = status;
+                       goto exit;
+               }
+       }
+
+       if (verbose && (ctx.count != 0)) {
+               logerror("... WROTE: %d bytes, %d segments, avg %d\n",
+                       (int)ctx.total, (int)ctx.count, (int)(ctx.total/ctx.count));
+       }
+
+       /* if required, reset the CPU so it runs what we just uploaded */
+       if (cpucs_addr && !ezusb_cpucs(device, cpucs_addr, true))
+               ret = -1;
+
+exit:
+       fclose(image);
+       return ret;
+}