Subversion Repositories usb_fpga_2_14

/*%
   Java host software API of ZTEX SDK
   Copyright (C) 2009-2017 ZTEX GmbH.
   http://www.ztex.de
 
   This Source Code Form is subject to the terms of the Mozilla Public
   License, v. 2.0. If a copy of the MPL was not distributed with this file,
   You can obtain one at http://mozilla.org/MPL/2.0/.
 
   Alternatively, the contents of this file may be used under the terms
   of the GNU General Public License Version 3, as described below:
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License version 3 as
   published by the Free Software Foundation.
 
   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, see http://www.gnu.org/licenses/.
%*/
 
package ztex;
 
/**
  * This class represents the configuration data space of ZTEX FPGA Boards that support it.
  * The internal format is (byte order is LE -- least significant byte first)
  * <pre>
  * &lt;Address&gt; &lt;Description&gt;
  * 0..2      Signature "CD0"
  * 3         Kind of FPGA Board, see {@link #boardNames}, e.g. 2 for "ZTEX USB-FPGA Module",
  * 4         FPGA Board series, e.g. 2
  * 5         FPGA Board number (number behind the dot), e.g. 16
  * 6..7      FPGA Board variant (letter), e.g. "b"
  * 8..9      FPGA, see {@link #fpgas}, e.g. 12 for X7A200T
  * 10        FPGA package, see {@link #packages}, e.g. 3 for FBG484
  * 11..13    Speed grade + temperature range, e.g. "2C"
  * 14        RAM size, format is ( n & 0xf0 ) << ( (n & 0xf) + 16 ) bytes
  * 15        RAM type, see {@link #ramTypes}
  * 16..25    Serial number, overwrites SN_STRING of the ZTEX descriptor.  
  *           If it is equal to "0000000000" (default) it is replaced by the unique MAC address.
  * 26..27    Actual size of Bitstream in 4K sectors; 0 means Bitstream disabled (default)
  * 28..29    Maximum size of Bitstream in 4K sectors; 0 means that either no Flash
  *           is present or that this information is stored in Flash (exchangeable media)
  * 30..31    Start of the Bitstream in 4K sectors
  * 32..33    USB vendor ID, ignored if zero
  * 34..35    USB product ID, ignored if USB vendor ID is zero
  * 36..67    Product string,  null-terminated if length is smaller than 32
  * 68..79    Reserved, must be 0
  * 80..127   48 bytes user space 
  * </pre>
  */   
 
public class ConfigData {
 
/** 
  * Kinds of FPGA Boards. 
  * It's defined as
  * <pre>{@code
public static final String boardNames[] = {
    "(unknown)" ,             // 0
    "ZTEX FPGA Module" ,      // 1
    "ZTEX USB-FPGA Module"    // 2, FX2 based
    "ZTEX USB3-FPGA Module"   // 3, FX3 based
};}</pre>
  **/
    public static final String boardNames[] = {
	"(unknown)" ,             // 0
	"ZTEX FPGA Module" ,      // 1
	"ZTEX USB-FPGA Module",   // 2, FX2 based
	"ZTEX USB3-FPGA Module"   // 3, FX3 based
    };
 
/**
  * FPGA's used on ZTEX FPGA Boards.
  * It's defined as
  * <pre>{@code
public static final String fpgas[] = {
	"(unknown)" ,  // 0
	"XC6SLX9" ,    // 1
	"XC6SLX16" ,   // 2
	"XC6SLX25" ,   // 3
	"XC6SLX45" ,   // 4
	"XC6SLX75" ,   // 5
	"XC6SLX100" ,  // 6
	"XC6SLX150" ,  // 7
	"XC7A35T",     // 8
	"XC7A50T",     // 9
	"XC7A75T",     // 10
	"XC7A100T",    // 11
	"XC7A200T",    // 12
	"Quad-XC6SLX150",  // 13
	"XC7A15T",     // 14
};}</pre>
  **/
    public static final String fpgas[] = {
	"(unknown)" ,  // 0
	"XC6SLX9" ,    // 1
	"XC6SLX16" ,   // 2
	"XC6SLX25" ,   // 3
	"XC6SLX45" ,   // 4
	"XC6SLX75" ,   // 5
	"XC6SLX100" ,  // 6
	"XC6SLX150" ,  // 7
	"XC7A35T",     // 8
	"XC7A50T",     // 9
	"XC7A75T",     // 10
	"XC7A100T",    // 11
	"XC7A200T",    // 12
	"Quad-XC6SLX150",  // 13
	"XC7A15T",     // 14
    };
 
/** * FPGA packages used on ZTEX FPGA boards.
  * It's defined as
  * <pre>{@code
public static final String packages[] = {
	"(unknown)",  // 0
	"FTG256" ,    // 1  256 balls, 1.0mm
	"CSG324" ,    // 2  324 balls, 0.8mm
	"CSG484" ,    // 3  484 balls, 0.8mm
	"FBG484"      // 4  484 balls, 1.0mm
};}</pre>
  **/
    public static final String packages[] = {
	"(unknown)",  // 0
	"FTG256" ,    // 1  256 balls, 1.0mm
	"CSG324" ,    // 2  324 balls, 0.8mm
	"CSG484" ,    // 3  484 balls, 0.8mm
	"FBG484"      // 4  484 balls, 1.0mm
    };
 
/** * RAM types and speed used on ZTEX FPGA boards.
  * It's defined as
  * <pre>{@code
public static final String ramTypes[] = {
	"(unknown)",        // 0
	"DDR-200 SDRAM",    // 1
	"DDR-266 SDRAM",    // 2
	"DDR-333 SDRAM",    // 3
	"DDR-400 SDRAM",    // 4
	"DDR2-400 SDRAM",   // 5
	"DDR2-533 SDRAM",   // 6
	"DDR2-667 SDRAM",   // 7
	"DDR2-800 SDRAM",   // 8
	"DDR2-1066 SDRAM"   // 9
};}</pre>
  **/
    public static final String ramTypes[] = {
	"(unknown)",        // 0
	"DDR-200 SDRAM",    // 1
	"DDR-266 SDRAM",    // 2
	"DDR-333 SDRAM",    // 3
	"DDR-400 SDRAM",    // 4
	"DDR2-400 SDRAM",   // 5
	"DDR2-533 SDRAM",   // 6
	"DDR2-667 SDRAM",   // 7
	"DDR2-800 SDRAM",   // 8
	"DDR2-1066 SDRAM",  // 9
	"DDR3-800 SDRAM",   // 10
	"DDR3-1066 SDRAM"   // 11
    };
 
    private byte[] data = new byte[128];  // data buffer
    private Ztex1v1 ztex = null;
 
 
/** 
 * Constructs an empty instance.
 */
   public ConfigData() {
	data[0] = 67;
	data[1] = 68;
	data[2] = 48;
	for ( int i=3; i<128; i++)
	    data[i] = 0;
	for ( int i=16; i<26; i++)
	    data[i] = 48;
   }
 
/** 
  * Constructs an instance and connects it with z. Also see {@link #connect(Ztex1v1)}.
  * @param z The ztex device to connect with.
  * @throws InvalidFirmwareException if interface 1 is not supported.
  * @throws UsbException If a communication error occurs.
  * @throws CapabilityException If no MAC-EEPROM support is present.
  */
   public ConfigData( Ztex1v1 z ) throws InvalidFirmwareException, UsbException, CapabilityException {
	this();
	connect(z);
   }
 
 
/** 
  * Reads the configuration data (if existent) from a device and connects it to this instance. 
  * After this user defined settings (e.g. serial number, bitstream size) are 
  * stored on device immediately after they are altered.
  * @param z The ztex device to connect with.
  * @return True if configuration data could be read.
  * @throws InvalidFirmwareException If interface 1 is not supported.
  * @throws UsbException If a communication error occurs.
  * @throws CapabilityException If no MAC-EEPROM support is present.
  */
   public boolean connect( Ztex1v1 z ) throws InvalidFirmwareException, UsbException, CapabilityException {
	ztex = z;
	if ( ztex == null ) return false;
 
	byte[] buf = new byte[128];
        ztex.macEepromRead(0,buf,128);
        if ( buf[0]==67 && buf[1]==68 && buf[2]==48 ) {
    	    for ( int i=3; i<128; i++)
		data[i] = buf[i];
	    return true;
	}
	return false;
   }
 
 
/** 
  * Disconnects the currently connected device.
  * After this modified settings are not stored on device anymore.
  * @return True if a device was connected.
  */
   public boolean disconnect() {
	if ( ztex == null ) return false;
	ztex = null;
	return true;
    }
 
 
/** 
  * Returns a copy of the configuration data array.
  * @return A copy of the configuration data array.
  */
   public byte[] data () {
	byte[] buf = new byte[128];
    	for ( int i=0; i<128; i++)
	    buf[i] = data[i];
	return buf;
   }
 
 
/** 
  * Returns a string of an array of strings including range check.
  */
   private String stringOfArray (String[] a, int i) {
	if ( i > a.length || i < 0 ) i = 0;
	return a[i];
    }
 
 
/** 
  * Finds a string from array.
  */
   private int findFromArray ( String[] a, String s) {
	int i = 0;
	while ( i < a.length && !a[i].equals(s) ) i++;
	if ( i >= a.length ) {
	    System.err.print("Invalid value: `" + s + "'. Possible values: `" + a[1] + "'");
	    for (int j=2; j<a.length; j++ )
		System.out.print(", `" + a[j] + "'");
	    System.out.println();
	    i = 0;
	}
	return i;
    }
 
 
/** 
  * Returns a string from data.
  */
   private String stringFromData (int start, int maxlen) {
	int i = 0;
	while ( i < maxlen && data[start+i] != 0 ) i++;
	return new String(data,start,i);
    }
 
 
/** 
  * send data
  * returns true if data was sent
  */
   private boolean sendData ( int start, int len) throws InvalidFirmwareException, UsbException, CapabilityException {
	if ( ztex == null ) return false;
	if ( start < 0 ) start = 0;
	if ( len > 128-start ) len = 128-start;
	if ( len <= 0 ) return false;
	byte[] buf = new byte[len];
	for ( int i=0; i<len; i++ ) 
	    buf[i] = data[start+i];
	ConfigData c = ztex.config;
	ztex.config = null;
        ztex.macEepromWrite(start,buf,len);
	ztex.config = c;
        return true;
    }
 
/** 
  * Convert string to data.
  */
   private void stringToData (String s, int start, int maxlen) {
	if ( s == null ) {
    	    for ( int i=0; i<maxlen; i++ ) {
    		data[start+i] = 0;
	    }
	}
	else {
    	    byte buf[] = s.getBytes();
    	    for ( int i=0; i<maxlen; i++ ) {
    		data[start+i] = i<buf.length ? buf[i] : 0;
	    }
	}
    }
 
/** 
  * Returns the name of the FPGA Board.
  * @return The name of the FPGA Board.
  */
   public String getName () {
	return stringOfArray(boardNames,data[3]) + " " + data[4] + "." +  (data[5] / 10) + (data[5] % 10) + stringFromData(6,2);
   }
 
/** 
  * Returns the major version number, e.g. 2 for USB-FPGA Modules 2.14b.
  * @return the major version number.
  */
   public byte getMajorVersion () {
	return data[4];
   }
 
/** 
  * Returns the minor version number, e.g. 14 for USB-FPGA Modules 2.14b.
  * @return the minor version number.
  */
   public byte getMinorVersion () {
	return data[5];
   }
 
/** 
  * Returns the variant letter, e.g. "b" for USB-FPGA Modules 2.14b.
  * @return the variant letter.
  */
   public String getVariant () {
	return stringFromData(6,2);
   }
 
 
/** 
  * Sets the name of the FPGA Board. 
  * Example: <pre>setName("ZTEX USB-FPGA Module", 2, 16, "b");  // denotes "ZTEX USB-FPGA Module 2.16b"</pre>
  * This setting is not transferred to the FPGA Board because is should not be altered by the user.
  * @param kind Kind of FPGA Board, see {@link #boardNames} for possible values, e.g. "ZTEX USB-FPGA Module"
  * @param series FPGA Board series, e.g. 2
  * @param number FPGA Board number (number behind the dot), e.g. 16
  * @param variant FPGA Board variant (letter), e.g. "b"
 */
   public void setName ( String kind, int series, int number, String variant) {
	data[3] = (byte) findFromArray(boardNames, kind);
	data[4] = (byte) (series & 255);
	data[5] = (byte) (number & 255);
	stringToData(variant,6,2);
   }
 
/** 
  * Returns FPGA information. 
  * Notation of the result is &lt;name&gt;-&lt;package&gt;-&lt;speed grade and temperature range&gt;, e.g. XC7A200T-FBG484-2C.
  * @return FPGA Information.
  */
   public String getFpga () {
	return stringOfArray(fpgas, (data[8] & 255) | ((data[9] & 255) << 8)) + "-" + stringOfArray(packages, data[10]) + "-" + stringFromData(11,3);
   }
 
/** 
  * Sets FPGA information. 
  * Example: <pre>setFpga("XC7A200T", "FBG484", "2C");   // denotes Xilinx part number XC7A200T-2FBG484C</pre>
  * This setting is not transferred to the FPGA Board because is should not be altered by the user.
  * @param name Name of the FPGA, see {@link #fpgas} for possible values, e.g. "XC7A200T"
  * @param pckg FPGA package, see {@link #packages} for possible values, e.g. "FBG484"
  * @param sg Speed grade and temperature range, e.g. "2C"
 */
   public void setFpga ( String name, String pckg, String sg) {
	int i = findFromArray(fpgas, name);
	data[8] = (byte) (i & 255);
	data[9] = (byte) ((i>>8) & 255);
	data[10] = (byte) findFromArray(packages, pckg);
	stringToData(sg,11,3);
   }
 
/** 
  * Returns RAM type and speed. 
  * @return FPGA Information.
  */
   public String getRamType () {
	return stringOfArray(ramTypes, (data[15] & 255));
   }
 
/** 
  * Returns RAM size in bytes. 
  * @return RAM size in bytes.
  */
   public int getRamSize () {
	return (data[14] & 0xf0) << ( (data[14] & 0xf) + 16 );
   }
 
/** 
  * Sets RAM information. 
  * Example: <pre>setRam(128, "DDR2-800 SDRAM");   // sets RAM info to 128 MB DDR2-800 SDRAM</pre>
  * This setting is not transferred to the FPGA Board because is should not be altered by the user.
  * @param size RAM size in MBytes, e.g. 128
  * @param type RAM type and speed, see {@link #ramTypes} for possible values, e.g. "DDR2-800 SDRAM"
 */
   public void setRam ( int size, String type) {
	if (size<0 || size>480*1024) {
	    System.err.println("Warning: Invalid RAM size: `" + size + "'. Possible values are 0 to 480*1024.");
	    size = 0;
	}
	int i=0;
	while (size >= 16) {
	    i++;
	    size = size >> 1;
	}
	data[14] = (byte) ((size << 4) | (i & 15));
	data[15] = (byte) findFromArray(ramTypes, type);
   }
 
/** 
  * Returns maximum size of bitstream in bytes.
  * This is the amount of flash which should be reserved for the bitstream.
  * @return Maximum size of bitstream in bytes sectors.
  */
   public int getMaxBitstreamSize () {
	return ( (data[28] & 255) | ((data[29] & 255) << 8) ) * 4096;
   }
 
/** 
  * Sets the maximum size of bitstream in 4 KByte sectors.
  * This setting is not transferred to the FPGA Board because is should not be altered by the user.
  * @param size4k Maximum size of bitstream in 4 KByte sectors. E.g. a value of 256 reserves 1 MByte for the bitstream.
 */
   public void setMaxBitstreamSize ( int size4k ) {
	data[28] = (byte) (size4k & 255);
	data[29] = (byte) ((size4k>> 8) & 255);
   }
 
/** 
  * Returns bitstream start position in bytes.
  * On devices which boot from flash the first sectors are reserved for the firmware.
  * @return Bitstream start position in bytes.
  */
   public int getBitstreamStart () {
	return ( (data[30] & 255) | ((data[31] & 255) << 8) ) * 4096;
   }
 
/** 
  * Sets the start position of the bitstream in 4 KByte sectors.
  * This setting is not transferred to the FPGA Board because is should not be altered by the user.
  * @param start4k Bitstream start position in 4 KByte sectors. E.g. a value of 128 reserves 512 KByte for the bitstream.
 */
   public void setBitstreamStart ( int start4k ) {
	data[30] = (byte) (start4k & 255);
	data[31] = (byte) ((start4k>> 8) & 255);
   }
 
/** 
  * Returns actual size of bitstream in bytes sectors.
  * 0 means that no bitstream is stored. The value is rounded up to a multiples of 4096.
  * @return Actual size of bitstream in byte sectors.
  */
   public int getBitstreamSize () {
	return ( (data[26] & 255) | ((data[27] & 255) << 8) ) * 4096;
   }
 
/** 
  * Sets the actual size of bitstream in bytes. The value is rounded up to a multiple of 4096.
  * If a device is connected, this setting is transferred to the FPGA Board.
  * A warning is printed if bitstream size is larger then the reserved size (see {@link #getMaxBitstreamSize()}).
  * @param size Actual size of bitstream in bytes.
  * @return True if a device is connected and setting was send.
  * @throws InvalidFirmwareException If interface 1 is not supported.
  * @throws UsbException If a communication error occurs.
  * @throws CapabilityException If no MAC-EEPROM support is present.
 */
   public boolean setBitstreamSize ( int size ) throws InvalidFirmwareException, UsbException, CapabilityException {
	if ( size < 0 ) size = 0;
	size = (size + 4095) >> 12;
	int i = (data[28] & 255) | ((data[29] & 255) << 8);
	if ( size > i )  System.err.println("Warning: Bitstream size of " + size + " 4K sectors larger than reserved memory of " + i + " 4K sectors");
	data[26] = (byte) (size & 255);
	data[27] = (byte) ((size>> 8) & 255);
	return sendData(26,2);
   }
 
/** 
  * Sets the serial number. 
  * During start-up the firmware overwrites SN_STRING from the ZTEX descriptor (see {@link ZtexDevice1}) by this value.  
  * If it is equal to "0000000000" (default) it is replaced by the unique MAC address. <p>
  * This setting is transferred to the FPGA Board.
  * Change takes effect after the next restart of the firmware.
  * @param sn Serial number string. Only the first 10 characters are considered.
  * @return True if a device is connected and setting was send.
  * @throws InvalidFirmwareException If interface 1 is not supported.
  * @throws UsbException If a communication error occurs.
  * @throws CapabilityException If no MAC-EEPROM support is present.
 */
   public boolean setSN ( String sn ) throws InvalidFirmwareException, UsbException, CapabilityException {
	stringToData(sn,16,10);
	return sendData(16,10);
   }
 
/** 
  * Set the USB vendor vendor and product ID. 
  * If vendor ID is 0 the default values from the firmware are used.
  * @param vid USB vendor ID.
  * @param pid USB product ID.
  * <p> This settings are transferred to the FPGA Board.
  * Change takes effect after the next restart of the firmware.
  * @return True if a device is connected and setting was send.
  * @throws InvalidFirmwareException If interface 1 is not supported.
  * @throws UsbException If a communication error occurs.
  * @throws CapabilityException If no MAC-EEPROM support is present.
 */
   public boolean setUsbIDs (int vid, int pid) throws InvalidFirmwareException, UsbException, CapabilityException {
	data[32] = (byte) (vid & 255);
	data[33] = (byte) ((vid>> 8) & 255);
	data[34] = (byte) (pid & 255);
	data[35] = (byte) ((pid>> 8) & 255);
	return sendData(32,4);
   }
 
/** 
  * Sets the product string.
  * If string is empty the firmware default is used.
  * <p> This setting is transferred to the FPGA Board.
  * Change takes effect after the next restart of the firmware.
  * @param ps The product string.
  * @return True if a device is connected and setting was send.
  * @throws InvalidFirmwareException If interface 1 is not supported.
  * @throws UsbException If a communication error occurs.
  * @throws CapabilityException If no MAC-EEPROM support is present.
 */
   public boolean setProductString ( String ps ) throws InvalidFirmwareException, UsbException, CapabilityException {
	stringToData(ps,36,32);
	return sendData(36,32);
   }
 
/** 
  * Returns user data at index i.
  * @param i the index. Valid values are 0 to 47.
  * @return User data.
  * @throws IndexOutOfBoundsException If i is smaller than 0 or greater than 47.
  */
   public byte getUserData (int i) {
	if ( i<0 || i>47 ) throw new IndexOutOfBoundsException ( "Invalid index: " + i + ". Valid range is 0 to 47.");
	return data[80+i];
   }
 
/** 
  * Sets user data at index i to value v. Use the method {@link #getMaxBitstreamSize()}
  * to transfer the data to the FPGA Board.
  * @param i The index. Valid values are 0 to 47.
  * @param v The value.
  * @throws IndexOutOfBoundsException If i is smaller than 0 or greater than 47.
  */
   public void setUserData (int i, byte v) throws IndexOutOfBoundsException {
	if ( i<0 || i>47 ) throw new IndexOutOfBoundsException ( "Invalid index: " + i + ". Valid range is 0 to 47.");
	data[80+i] = v;
   }
 
/** 
  * Sends the user data to the FPGA Board.
  * @return True if a device is connected and data could be send.
  * @throws InvalidFirmwareException If interface 1 is not supported.
  * @throws UsbException If a communication error occurs.
  * @throws CapabilityException If no MAC-EEPROM support is present.
  */
   public boolean sendtUserData () throws InvalidFirmwareException, UsbException, CapabilityException {
	return sendData(80,48);
   }
 
/** 
  * Returns the bitstream path if the same directory sheme as for the examples is used.
  * For USB-FPGA Modules 1.* and 2.0* (Spartan 6 FPGA) it is "usb-fpga-<major version number>.<minor version number><variant letter>/<project name>.bit", 
  * for later FPGA Boards it is "usb-fpga-<major version number>.<minor version number>/<project name>.runs/impl_<major version number>.<minor version number><variant letter>/<project name>.bit".
  * @param name The project name.
  * @return Standard bitstream path.
  */
   public String defaultBitstreamPath(String name) {
	return ( (getMajorVersion()<2) || ( (getMajorVersion()==2) && getMinorVersion()<10) ) ?
	    "fpga-" + getMajorVersion() + "." + ( getMinorVersion() / 10 ) +  ( getMinorVersion() % 10 ) + ztex.config.getVariant() + "/" + name + ".bit" :
	    "fpga-" + getMajorVersion() + "." + ( getMinorVersion() / 10 ) +  ( getMinorVersion() % 10 ) + "/" + name + ".runs/impl_" + getMajorVersion() + "_" + ( getMinorVersion() / 10 ) +  ( getMinorVersion() % 10 ) + ztex.config.getVariant() + "/" + name + ".bit";
   }
 
 
}