.\"  -*- nroff -*-
.\"  $Id: config_wrapper.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013-2022 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 is usually properly defaulted
based on the \fB\-\-board\fP option. Only in cases where 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 an 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 an FPGA with XILINX ISE \fBimpact\fP. The input \fIFILE\fP must be in
\fI.bit\fP format.
.
.\" ----------------------------------------------
.IP \fBjconfig\fP
Configure an FPGA with \fBjtag\fP(1). The input \fIFILE\fP must be in
\fI.svf\fP format. This subcommand is usually used for boards with a
Cypress FX2 USB controller, like the Digilent Nexys2, Nexys3, or Atlys,
and an FX2 firmware that emulates an Altera USB-Blaster programming cable.

The USB device path is defined by the environment variables \fBRETRO_FX2_VID\fP
and \fBRETRO_FX2_PID\fP, 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 subcommand 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 subcommand 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 subcommands,
mainly to locate the \fI.bsdl\fP files which describe the JTAG commands
of all devices in the JTAG chain.
.br
The 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>