Subversion Repositories w11

.\"  -*- nroff -*-
.\"  $Id: fx2load_wrapper.1 550 2014-02-03 08:16:57Z mueller $
.\"
.\" Copyright 2013- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\" 
.\" ------------------------------------------------------------------
.
.TH FX2LOAD_WRAPPER 1 2013-01-05 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
fx2load_wrapper \- auto-load firmware into Cypress FX2 USB controller
.\" ------------------------------------------------------------------
.SH SYNOPSIS
.
.SY fx2load_wrapper
.OP \-\-board=\fIb\fP
.OP \-\-file=\fIf\fP
.OP \-\-ihx_path=\fIp\fP
.OP \-\-cycfx2prog
.OP \-\-force
.OP \-\-dry_run
.
.SY fx2load_wrapper
.B \-\-help
.YS
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Checks firmware state of a Cypress FX2 USB controller and re-loads the
firmware in case of a mismatch of currently active and desired firmware.

The command locates a USB device with a USB path defined by the environment 
variables RETRO_FX2_VID and RETRO_FX2_PID, or default vid=16c0 and pid=03ef.
It inquires with \fBlsusb\fP(1) the 'iProduct' attribute of the currently
active USB descriptor. If this attribute is defined and equals the basename
of the firmware image given with  \fB-\-file\fP it is assumed the the proper
firmware is already active. Otherwise the firmware image is loaded with
either \fBfxload\fP(1) or \fBcycfx2prog\fP.

\fBNote:\fP after a firmware load the Cypress FX2 USB controller restarts. 
This causes a USB re-numeratation, the USB device disconnects and reconnects
with a new device descriptor. It can take some time till the Linux USB stack
shows the new device descriptor. The command sleeps for 1.5 seconds, this is 
usually enough to ensure that subsequent commands see the new state.
.
.\" ------------------------------------------------------------------
.SH OPTIONS
.
.\" ----------------------------------------------
.IP \fB\-\-board=\fIb\fR
determines the type of board to be configured. The default is 'nexys2',
currently supported boards are:
.RS
.PD 0
.IP \fBnexys2\fP
Digilent Nexys2. Default file: nexys2_jtag_2fifo_as.ihx
.IP \fBnexys3\fP
Digilent Nexys3. Default file: nexys3_jtag_2fifo_as.ihx
.IP \fBatlys\fP
Digilent Atlys. Default file: nexys3_jtag_2fifo_as.ihx
.RE
.PD
.
.\" ----------------------------------------------
.IP \fB\-\-file=\fIf\fR
specifies the firmware image to be loaded. Must be in \fI.ihx\fP format
and located in the path defined with the \fB\-\-ihx_path\fP option.
.
.\" ----------------------------------------------
.IP \fB\-\-ihx_path=\fIp\fR
specifies the directory were firmware image files are searched. The default
is \fI$RETROBASE/tools/fx2/bin\fP.
.
.\" ----------------------------------------------
.IP \fB\-\-cycfx2prog\fP
Use \fBcycfx2prog\fP instead of \fBfxload\fP(1) to load the firmware.
.
.\" ----------------------------------------------
.IP \fB\-\-force\fP
Unconditionally load the firmware, even when a 'iProduct' attribute match 
is seen. Useful to reset the Cypress FX2 controller.
.
.\" ----------------------------------------------
.IP \fB\-\-dry_run\fP
Don't load the firmware, display only the command used to do so.
.
.\" ----------------------------------------------
.IP \fB\-\-help\fP
print help text and exit.
.
.\" ------------------------------------------------------------------
.SH EXIT STATUS
In case of an error an exit status 1 is returned.
.
.\" ------------------------------------------------------------------
.SH ENVIRONMENT
.IP "\fBRETRO_FX2_VID, RETRO_FX2_PID\fR" 4
Define the USB path of the Cypress FX2 USB controller. If not specified
the defaults vid=16c0 and pid=03ef are used.
.IP \fBRETROBASE\fR
Path to current Retro project root directory. Used for the default
firmware path in case no \fB\-\-ihx_path\fP option given.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBfx2load_wrapper --board=nexys2 --file=nexys2_jtag_2fifo_ic.ihx\fR" 4
Checks whether the 'nexys2_jtag_2fifo_ic' version of the firmware is loaded
and in case not loads the firmware image.

.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR fxload (1),
.BR config_wrapper (1)

.\" ------------------------------------------------------------------
.SH AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>