.\"  -*- nroff -*-
.\"  $Id: config_wrapper.1 651 2015-02-26 21:32:15Z mueller $
.\"
.\" Copyright 2013- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\" 
.\" ------------------------------------------------------------------
.
.TH CONFIG_WRAPPER 1 2013-01-02 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
config_wrapper \- configure FPGA via ISE impact or Linux jtag
.\" ------------------------------------------------------------------
.SH SYNOPSIS
.
.SY config_wrapper
.OP \-\-board=\fIb\fP
.OP \-\-path=\fIp\fP
.I COMMAND
.I FILE
.
.SY config_wrapper
.B \-\-help
.YS
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Wrapper script to handle the configuration of an FPGA board with either
a XILINX JTAG programming cable and the ISE \fBimpact\fP program or with
an onboard Cypress FX2 USB controller and the \fBjtag\fP(1) program.
The \fICOMMAND\fP argument controls the action:

.RS 3
.PD 0
.IP \fBiconfig\fP 10
configure using \fBimpact\fP with \fI.bit\fP file \fIFILE\fP
.IP \fBjconfig\fP
configure using \fBjtag\fP(1) with \fI.svf\fP file \fIFILE\fP
.IP \fBbit2svf\fP
create a \fI.svf\fP file from the \fI.bit\fP file \fIFILE\fP
.PD
.
.\" ------------------------------------------------------------------
.SH OPTIONS
.
.\" ----------------------------------------------
.IP \fB\-\-board=\fIb\fR
determines the type of board to be configured. The default is 's3board',
currently supported boards are:
.RS
.RS 3
.PD 0
.IP \fBs3board\fP 10
Digilent S3BOARD. Default path: xc3s1000
.IP \fBnexys2\fP
Digilent Nexys2. Default path: xc3s1200e
.IP \fBnexys3\fP
Digilent Nexys3. Default path: xc6slx16
.IP \fBatlys\fP
Digilent Atlys. Default path: xc6slx45
.IP \fBsp605\fP
Xilinx SP605. Default path: xc6slx45t
.RE
.RE
.PD
.
.\" ----------------------------------------------
.IP \fB\-\-path=\fIp\fR
determines the type of FPGA to be configured. It usually properly defaulted 
based on the \fB\-\-board\fP option. Only in cases were a board is available
with several die sizes this option will be needed.
.
.\" ----------------------------------------------
.IP \fB\-\-help\fP
print help text and exit.
.
.\" ------------------------------------------------------------------
.SH COMMANDS
.
.\" ----------------------------------------------
.IP \fBbit2svf\fP
Convert a FPGA configuration file from \fI.bit\fP format (the native XILINX
format) to  \fI.svf\fP format (the portable Serial Vector Format). The
XILINX ISE \fBimpact\fP program is used, the input \fIFILE\fP must be in
\fI.bit\fP format.
.
.\" ----------------------------------------------
.IP \fBiconfig\fP
Configure a FPGA with XILINX ISE \fBimpact\fP. The input \fIFILE\fP must be in
\fI.bit\fP format.
.
.\" ----------------------------------------------
.IP \fBjconfig\fP
Configure a FPGA with \fBjtag\fP(1). The input \fIFILE\fP must be in
\fI.svf\fP format. This sub command is usually used for boards with a
Cypress FX2 USB controller, like the Digilent Nexys2, Nexys3 or Atlys, 
and a FX2 firmware which emulates an Altera USB-Blaster programming cable.

The USB device path is defined by the environment variables RETRO_FX2_VID
and RETRO_FX2_PID, or defaults to vid=16c0 and pid=03ef.

Use the \fBfx2load_wrapper\fP(1) command to ensure that the proper firmware
is loaded in the Cypress FX2 USB controller.
The \fBbit2svf\fP sub command can be used to create a \fI.svf\fP from
a \fI.bit\fP file.
.
.\" ------------------------------------------------------------------
.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
Used by the \fBjconfig\fP sub command to define the USB path of the
Cypress FX2 USB controller emulating an Altera USB-Blaster cable.
.IP \fBXILINX\fR
Path to current XILINX ISE installation. Required by all sub commands,
mainly to locate the \fI.bsdl\fP files which describe the JTAG commands
of all devices in the JTAG chain.
.br
Best is to use \fBconfig_wrapper\fP with the \fBxtwi\fP(1) wrapper, this will
automatically define this environment variable.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBconfig_wrapper bit2svf test.bit\fR" 4
Creates \fItest.svf\fP from \fItest.bit\fP.
.
.IP "\fBconfig_wrapper --board=nexys2 iconfig test.bit\fR"
Configures a Nexys2 board with \fItest.bit\fP using ISE \fBimpact\fP.
.
.IP "\fBconfig_wrapper --board=nexys3 jconfig test.svf\fR"
Configures a Nexys3 board with \fItest.svf\fP using \fBjtag\fP(1).
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR jtag (1),
.BR fx2load_wrapper (1),
.BR xtwi (1)

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