path: root/iceprog/iceprog.1

.\" 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:
<http://www.clifford.at/gallery/2014-elektronik/IMG_20141115_183838>
.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:
<https://github.com/cliffordwolf/icestorm/issues>
.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: <http://hedmen.org/icestorm-doc/>
.br
or available locally via: info \(aq(icestorm) iceprog invocation\(aq