/*
 * 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 <errno.h>

#include <libusb.h>
#include "log.h"
#include "ezusb.h"

/*
 * 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.
 */

/*
 * 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;

    log_debug("%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 != (ssize_t)len) {
        if (status < 0)
            log_debug("%s: %s\n", label, libusb_error_name(status));
        else
            log_debug("%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;

    log_debug("%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 != (ssize_t)len) {
        if (status < 0)
            log_debug("%s: %s\n", label, libusb_error_name(status));
        else
            log_debug("%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;

    log_debug("%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 libusbx as the device disappears */
        ((!doRun) || (status != LIBUSB_ERROR_IO)))
    {
        if (status < 0) {
            log_debug("Can't modify CPUCS: %s\n", mesg,
                      libusb_error_name(status));
        } else {
            log_debug("Can't modify CPUCS\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;

    log_debug("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 libusbx as the device disappears */
    if ((status != 0) && (status != LIBUSB_ERROR_IO))
    {
        if (status < 0) {
            log_debug("Failed to send jump command: %s\n",
                      mesg, libusb_error_name(status));
        } else {
            log_debug("Failed to send jump command\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) {
            log_debug("EOF without EOF record!\n");
            break;
        }

        /* EXTENSION: "# comment-till-end-of-line", for copyrights etc */
        if (buf[0] == '#')
            continue;

        if (buf[0] != ':') {
            log_debug("Not an ihex record: %s", buf);
            return -2;
        }

        /* ignore any newline */
        cp = strchr(buf, '\n');
        if (cp)
            *cp = 0;

        log_verbose("** 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;

        /* Sanity check for bogus length */
        if (len > (512 * 1024)) {
            log_debug("Encountered unexpectedly large length: %d\n", len);
            return -3;
        }

        /* 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) {
            log_verbose("EOF on hexfile\n");
            break;
        }

        if (type != 0) {
            log_debug("Unsupported record type: %u\n", type);
            return -3;
        }

        if ((len * 2) + 11 > strlen(buf)) {
            log_debug("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 (file_size < 0) {
        return -1;
    }

    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) {
            log_debug("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 */
            log_debug("IIC data block too small - please report this error to libusbx.org\n");
            return -1;
        }
        read_len = fread(data, 1, data_len, image);
        if (read_len != data_len) {
            log_debug("Read error: %s\n", strerror(errno));
            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) {
            log_debug("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) {
            log_debug("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) {
            log_debug("SKIP external RAM, %u bytes at 0x%08x\n",
                    (unsigned)len, addr);
            return 0;
        }
        break;
    case _undef:
    default:
        log_error("Bug @ %s:%d\n", __FILE__, __LINE__);
        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;

    image = fopen(path, "rb");
    if (image == NULL) {
        log_debug("Unable to open '%s' for input: %s\n", path,
                  strerror(errno));
        return -2;
    } else
        log_debug("Open firmware image %s for RAM upload\n", path);

    // Read header
    if (fread(hBuf, sizeof(char), sizeof(hBuf), image) != sizeof(hBuf)) {
        log_debug("Could not read image header: %s\n", strerror(errno));
        fclose(image);
        return -3;
    }

    // check "CY" signature byte and format
    if ((hBuf[0] != 'C') || (hBuf[1] != 'Y')) {
        log_debug("Image doesn't have a \"CY\" signature\n");
        fclose(image);
        return -3;
    }

    // Check bImageType
    switch(hBuf[3]) {
    case 0xB0:
        log_debug("Normal FW binary %s image with checksum\n", (hBuf[2]&0x01)?"data":"executable");
        break;
    case 0xB1:
        log_debug("Security binary image is not currently supported\n");
        fclose(image);
        return -3;
    case 0xB2:
        log_debug("VID:PID image is not currently supported\n");
        fclose(image);
        return -3;
    default:
        log_debug("Invalid image type 0x%02X\n", hBuf[3]);
        fclose(image);
        return -3;
    }

    // Read the bootloader version
    if ((ezusb_read(device, "Read bootloader version", RW_INTERNAL, 0xFFFF0020, blBuf, 4) < 0)) {
        log_debug("Could not read bootloader version\n");
        fclose(image);
        return -8;
    }
    log_debug("FX3 bootloader version: 0x%02X%02X%02X%02X\n", blBuf[3], blBuf[2], blBuf[1], blBuf[0]);

    dCheckSum = 0;
    log_debug("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
            log_debug("Could not read image");
            fclose(image);
            return -3;
        }
        if (dLength == 0)
            break; // done

        // Sanity check for bogus value
        if (dLength > (512 * 1024)) {
            log_debug("Encountered unexpectedly large length: %d\n", dLength);
            fclose(image);
            return -3;
        }

        dImageBuf = calloc(dLength, sizeof(uint32_t));
        if (dImageBuf == NULL) {
            log_debug("Could not allocate buffer for image chunk\n");
            fclose(image);
            return -4;
        }

        // read sections
        if (fread(dImageBuf, sizeof(uint32_t), dLength, image) != dLength) {
            log_debug("Could not read image");
            free(dImageBuf);
            fclose(image);
            return -3;
        }
        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)) {
                log_debug("R/W error\n");
                free(dImageBuf);
                fclose(image);
                return -5;
            }
            // Verify data: rBuf with bBuf
            for (i = 0; i < dLen; i++) {
                if (rBuf[i] != bBuf[i]) {
                    log_debug("Verify error");
                    free(dImageBuf);
                    fclose(image);
                    return -6;
                }
            }

            dLength -= dLen;
            bBuf += dLen;
            dAddress += dLen;
        }
        free(dImageBuf);
    }

    // read pre-computed checksum data
    if ((fread(&dExpectedCheckSum, sizeof(uint32_t), 1, image) != 1) ||
        (dCheckSum != dExpectedCheckSum)) {
        log_debug("Checksum error\n");
        fclose(image);
        return -7;
    }

    fclose(image);

    // transfer execution to Program Entry
    if (!ezusb_fx3_jump(device, dAddress)) {
        return -6;
    }

    return 0;
}

/*
 * Load a firmware file into target RAM. device is the open libusbx
 * 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 };

    if (fx_type == FX_TYPE_FX3)
        return fx3_load_ram(device, path);

    image = fopen(path, "rb");
    if (image == NULL) {
        log_debug("%s: Unable to open for input: %s\n", path, strerror(errno));
        return -2;
    } else
        log_debug("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)) ) {
            log_debug("IIC image does not contain executable code - cannot load to RAM.\n");
            fclose(image);
            return -1;
        }
    }

    /* 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)) {
            fclose(image);
            return -1;
        }

        /* 2nd stage, first part? loader was already uploaded */
    } else {
        ctx.mode = skip_internal;

        /* let CPU run; overwrite the 2nd stage loader later */
        log_debug("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) {
        log_debug("Unable to upload %s\n", path);
        fclose(image);
        return status;
    }

    /* 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)) {
            fclose(image);
            return -1;
        }

        /* at least write the interrupt vectors (at 0x0000) for reset! */
        rewind(image);
        log_debug("2nd stage: write on-chip memory\n");
        status = parse_ihex(image, &ctx, is_external, ram_poke);
        if (status < 0) {
            log_error("Unable to completely upload %s\n", path);
            fclose(image);
            return status;
        }
    }

    log_debug("Wrote: %d bytes, %d segments\n",
              (int)ctx.total, (int)ctx.count);

    fclose(image);

    /* if required, reset the CPU so it runs what we just uploaded */
    if (cpucs_addr && !ezusb_cpucs(device, cpucs_addr, true))
        return -1;

    return 0;
}
