From b61cfb8a011330b3621734b134ce3b56d7507b2e Mon Sep 17 00:00:00 2001 From: Roland Lutz Date: Mon, 12 Jun 2017 20:02:34 +0200 Subject: iceprog: Add manpage --- iceprog/Makefile | 3 ++ iceprog/iceprog.1 | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+) create mode 100644 iceprog/iceprog.1 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: + +.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 -- cgit v1.2.3