.\" Manpage for iceprog(1) .\" Copyright (C) 2017 Roland Lutz .\" .\" Permission is granted to copy, distribute and/or modify this document .\" under the terms of the GNU Free Documentation License, Version 1.3 or .\" any later version published by the Free Software Foundation; with no .\" Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. .\" .TH ICEPROG "1" "June 2017" "IceStorm" "User Commands" .SH NAME iceprog \- simple programming tool for FTDI\-based Lattice iCE programmers .SH SYNOPSIS .B iceprog [\-b|\-n|\-c] \fIINPUT\-FILE\fR .B iceprog \-r|\-R\fI\,BYTES\fR \fIOUTPUT\-FILE\fR .B iceprog \-S \fIINPUT\-FILE\fR .B iceprog \-t .SH DESCRIPTION The \fBiceprog\fR program is a simple programming tool for FTDI\-based Lattice iCE programmers which can read, write and erase the flash and write the SRAM of an FPGA. It is typically invoked after the bitstream has been converted by \fBicepack\fR to the iCE40 \fB.bin\fR format as the last step of the build process to transfer the bitstream to the FPGA. .SS Operation mode When no special option is given, \fBiceprog\fR erases all 64kB sectors which would be touched by the written data, writes the data to the flash, and then reads it back and verifies it. \fIPlease note:\fR If the data is not aligned to 64kB, some data before (if \fB\-o\fR is used) and after the written data may be erased as well. The way the flash is erased can be changed with the following options: .TP \fB\-b\fR Bulk erase the entire flash before writing. When using this option, \fBiceprog\fR can be invoked without an \fIINPUT\-FILE\fR; in this case, the flash is just bulk erased, and nothing is written. .TP \fB\-n\fR Don't erase the flash before writing. .PP Instead of the default erase/write/verify, \fBiceprog\fR can perform some other operations: .TP \fB\-c\fR Just read the data which would have been written from the flash and verify it (`check'). .TP \fB\-r\fR Read the first 256 kB from flash and write them to a file. .TP \fB\-R\fR \fISIZE\-IN\-BYTES\fR Read the specified number of bytes from the flash and write them to a file. You can append `\fBk\fR' to the size to specify it in kilobytes and `\fBM\fR' to specify it in megabytes. .TP \fB\-S\fR Perform SRAM programming. .TP \fB\-t\fR Just read the flash ID sequence. .PP All of the above options are mutually exclusive. .SS General options .TP \fB\-d\fR \fIDEVICE\-STRING\fR Use the specified USB device instead of the default one (which is vendor ID 0x0403 and device ID 0x6010). The supported notations for \fIDEVICE\-STRING\fR are: \fBd:\,\f(BIdevicenode\fR \- path of the bus and device node within USB device tree (usually at /proc/bus/usb/); e.g., `d:002/005' \fBi:\,\f(BIvendor\/\fB:\,\f(BIproduct\fR \- first device with given vendor and product ID. IDs can be decimal, octal (preceded by `\fB0\fR'), or hex (preceded by `\fB0x\fR'); e.g., `i:0x0403:0x6010' \fBi:\,\f(BIvendor\/\fB:\,\f(BIproduct\/\fB:\,\f(BIindex\fR \- same as above, with index being the number of the device (starting with 0) if there is more than one device with this vendor and product ID; e.g., `i:0x0403:0x6010:0' \fBs:\,\f(BIvendor\/\fB:\,\f(BIproduct\/\fB:\,\f(BIserial\-string\fR \- first device with given vendor ID, product ID and serial string. .TP \fB\-I\fR A|B|C|D Connect to the specified interface on the FTDI chip. If this option is omitted, interface A is used. .TP \fB\-o\fR \fIOFFSET\-IN\-BYTES\fR Start reading/writing at address \fIOFFSET\-IN\-BYTES\fR instead of the beginning of the memory. You can append `\fBk\fR' to the offset to specify it in kilobytes and `\fBM\fR' to specify it in megabytes. .TP \fB\-v\fR Write more verbose messages. .TP \fB\-\-help\fR Display a help text and exit. .SS Exit status .TP .B 0 on success, .TP .B 1 if a non\-hardware error occurred (e.g., failure to read from or write to a file, or invoked with invalid options), .TP .B 2 if communication with the hardware failed (e.g., cannot find the iCE FTDI USB device), .TP .B 3 if verification of the data failed. .SS Notes for iCEstick (iCE40HX\-1k devel board) An unmodified iCEstick can only be programmed via the serial flash. Direct programming of the SRAM is not supported. For direct SRAM programming the flash chip and one zero ohm resistor must be desoldered and the FT2232H SI pin must be connected to the iCE SPI_SI pin, as shown in this picture: .SS Notes for the iCE40\-HX8K Breakout Board Make sure that the jumper settings on the board match the selected mode (SRAM or FLASH). See the iCE40\-HX8K user manual for details. .SH AUTHOR Written by Clifford Wolf. .SH REPORTING BUGS If you have a bug report, please file an issue on github: .SH COPYRIGHT Most of Project IceStorm is licensed under the ISC license: Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .SH SEE ALSO Full documentation at: .br or available locally via: info \(aq(icestorm) iceprog invocation\(aq