                        CYPRESS SEMICONDUCTOR CORPORATION
                                    FX3 SDK

ELF to Boot Image Convertor
---------------------------

  This folder contains a utility to convert the ELF binary of the FX3 firmware
  into the boot image format that is used by the FX3 boot-loader.
  
  The boot image format is expected by the FX3 boot-loader when booting from an
  I2C/SPI EEPROM or through the GPIF port.  The same format is used by the
  Cypress tools (Control Center) when booting the device through the USB port.

  The utility is provided both in C source form and executable binary for
  Windows platforms.  The C source can be compiled using any ANSI C compiler.

  Usage:
  ------
    The utility is a console application that needs to be invoked with the
    following options.

    elf2img.exe -i <elf filename> -o <image filename> [-i2cconf <eeprom control>]
                [-vectorload <vecload>] [-imgtype <image type>] [-v] [-h]

    Where
      <elf filename> is the input ELF file name with path
      <image filename> is the output file name with path
      <eeprom control> is the I2C/SPI EEPROM control word in hexadecimal form
      <image type> is the image type byte in hexadecimal
      -v is used for verbose logs during the conversion process
      -h is used to print this help information

    Image Type
    ----------
      The <image type> should be 0xB0 for all firmware applications. Other values
      are reserved.

    Interrupt Vector Load
    ---------------------
      The ARM926EJ-S core on the FX3 device has its reset and interrupt vectors
      stored in the first 256 bytes of memory (address range 0x00 - 0x100). It
      is not advisable to load any code directly into this address range as it
      may interfere with the boot loader or active firmware operation. The FX3
      firmware library and default linker settings ensure that no valid code is
      to be loaded directly into this address range. The interrupt vectors are
      safely copied into this area once the firmware starts running.

      The elf2img utility in default mode removes any data in the address range
      0x00 - 0x100 while generating the boot image. This is safe because the
      recommended linker settings ensure that no valid code/data is placed in
      this address range.

      This behavior can be over-ridden using the -vectorload command line option.
      The <vecload> value is a yes/no string, which when set to "yes" causes
      the tool to retain any data in this address range in the boot image. The
      default value for this parameter is "no".

    EEPROM Control
    --------------
      This parameter is only applicable in the case of boot from I2C EEPROM or
      SPI FLASH.  If the FX3 is being booted via USB or the GPIF port, this field
      is not used and can be omitted while generating the img file.

      In the case of I2C boot, the <eeprom control> byte specifies the type and
      speed of the EEPROM used.

      In the case of SPI boot, the <eeprom control> byte specifies the speed at
      which the SPI boot from EEPROM should be performed.

      This byte is a don't care when any other boot mode is used.

      I2C Parameters:
      ---------------
        The encoding in the case of I2C boot is as follows:

        Bit      0: Must be zero.
        Bits 3 - 1: EEPROM size
                    7 = 128 KB (Microchip), 6 = 64 KB, 5 = 32 KB, 4 = 16 KB,
                    3 = 8 KB, 2 = 4 KB
        Bits 5 - 4: EEPROM speed
                    0 = 100 KHz, 1 = 400 KHz, 2 = 1 MHz
        Bits 7 - 6: Must be zero.

        The default value used for this field is 0x1C which corresponds to the use
        of one or more 64 KB Atmel EEPROMs at a frequency of 400 KHz. This default
        value works for the I2C EEPROM that is present on the FX3 DVK.

      SPI Parameters:
      ---------------
        The encoding in the case of SPI boot is as follows:

        Bit      0: Must be zero.
        Bits 3 - 1: Don't care
        Bits 5 - 4: SPI operating frequency
                    0 = 10 MHz, 1 = 20 MHz, 2 = 30 MHz
        Bits 7 - 6: Must be zero.

        The default value generated by the elf2img tool is 0x1C, which means that
        the default SPI boot frequency is 20 MHz.

[]

