iceprog: Add manpage

2 files changed, 158 insertions, 0 deletions

diff --git a/iceprog/Makefile b/iceprog/Makefile
index 286460f..c61b470 100644
--- a/iceprog/Makefile
+++ b/iceprog/Makefile
@@ -24,9 +24,12 @@ iceprog$(EXE): iceprog.o
 install: all
 	mkdir -p $(DESTDIR)$(PREFIX)/bin
 	cp iceprog $(DESTDIR)$(PREFIX)/bin/iceprog
+	mkdir -p $(DESTDIR)$(PREFIX)/share/man/man1
+	install -c -m 644 iceprog.1 $(DESTDIR)$(PREFIX)/share/man/man1
 
 uninstall:
 	rm -f $(DESTDIR)$(PREFIX)/bin/iceprog
+	rm -f $(DESTDIR)$(PREFIX)/share/man/man1/iceprog.1
 
 clean:
 	rm -f iceprog
diff --git a/iceprog/iceprog.1 b/iceprog/iceprog.1
new file mode 100644
index 0000000..22d3882
--- /dev/null
+++ b/iceprog/iceprog.1
@@ -0,0 +1,155 @@
+.\" 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