.\" http://neil.franklin.ch/Projects/VirtexTools/Makefile
.\" author Neil Franklin, last modification 2002.09.22
.\"
.TH VD 1 "2002.09.22" "VirtexTools"
.SH NAME
vd \- VirtexDump, textual dump of Virtex bitstreams
.SH SYNOPSIS
.B vd
[\fI\-sqlfemzvh\fP] [\fI\-r range\fP] [\fI\-t base\fP[\fIbyte\fP]]
[\fI\-o file\fP] [\fIbitfile\fP]
.SH DESCRIPTION
The \fBvd\fP (VirtexDump) program is a utility to dump the contents of an
Xilinx \fIVirtex FPGA bitstream\fP (.bit file) \fIbitfile\fP (default
\fIstdin\fP) as an text.
.PP
For this the user can select the \fIrange\fP processed and a wide selection
of \fIformating options\fP to get just the type of dump of those internals
he is interested in.
.SH OPTIONS
.TP
.B "\-s"
short format: data and addresses, no headers or labels
(default is data with headers and labels and addresses)
.TP
.B "\-q"
quiet format: just data, no headers or labels or addresses. Overrides \fI\-s\fP
.TP
.B "\-l"
LUTs only: only dump LUTs, suppress FFs (default is both)
.TP
.B "\-f"
flipflops only: only dump FFs, suppress LUTs.
.RS
.PP
Together with \fI\-l\fP both LUTs and FFs are suppressed, only headers and
labels and addresses appear, as far as \fI\-s\fP and \fI\-q\fP allow
(\fI\-lfq\fP sums up (or subtracts down) to delivering empty lines)
.RE
.TP
.B "\-e"
entire element: dump entire CLB configuration as an 48x18 bit pattern, not
just the LUTs+FFs. \fI\-s\fP and \fI\-q\fP have here the same effects as
usual, \fI\-l\fP and \fI\-f\fP have no effect on this, \fIslice\fP and
\fILUT\fP letters in \fIrange\fP are ignored
.TP
.B "\-m"
memory mode: LUTs are regarded as LUT-RAMs, rows are merged to an single memory
and displayed rotated (bits horizontal, address vertical). Overrides \fI\-e\fP.
\fI\-s\fP and \fI\-q\fP have here the same effects as usual, \fI\-l\fP and
\fI\-f\fP have no effect on this
.TP
.B "\-z"
zigzag memory: LUTS are regarded as LUT-RAM32s with bits 0/2/../n-2 in first
slice and bits 1/3/../n-1 in second slice. Has no effect without \fI\-m\fP
.TP
.B "\-v"
verbose operation: send running activity report to \fIstderr\fP 
.TP
.B "\-h"
help: display an short help text, summarising this man page, then abort without
processing anything
.TP
.B "\-r" \fIspec\fP
restrict range to dump to only: [\fIhorizontal\fP][\fI/vertical\fP] (default
\fIfull chip\fP), where:
.RS
.TP
.B "horizontal"
is [\fIleft\fP][\fI\-\fP[\fIright\fP]], such as \fI14\fP (only one) or
\fI7-\fP (to end) or \fI6-17\fP (range) or \fI-23\fP (from begin).
\fIleft\fP must be smaller than \fIright\fP else nothing is dumped
.TP
.B "vertical"
is [\fIbottom\fP][\fI\-\fP[\fItop\fP]], same examples as horizontal.
\fIbottom\fP must be smaller than \fItop\fP else nothing is dumped
.TP
.B "left"
and
.TP
.B "right"
are \fIcolumn\fP[\fIslice\fP], such as \fI14\fP or \fI5L\fP or \fI23R\fP.
.RS
.PP
Without \fIslice\fP both slices are of that \fIcolumn\fP are included.
.PP
\fBleft\fP with \fIR\fP and \fBright\fP with \fIL\fP simply restrict away
first and last \fIslice\fP.
.PP
\fBleft\fP with \fIL\fP and \fBright\fP with \fIR\fP (which would do
same as nothing) restrict to only \fIL\fP or \fIR\fP side \fIslices\fP
.RE
.TP
.B "bottom"
and
.TP
.B "top"
are \fIrow\fP[\fILUT\fP], such as \fI14\fP or \fI5F\fP or \fI23G\fP
.RS
.PP
Effect of the facultative \fIF\fP and \fIG\fP is identical to \fIL\fP and
\fIR\fP above
.RE
.TP
.B "column"
and
.TP
.B "row"
are numbers of \fI0\fP to \fIsize-1\fP (numbered from the left or bottom of
FPGA)
.TP
.B "slice"
is \fIL\fP (left = slice 1) or \fIR\fP (right = slice 0)
.TP
.B "LUT"
is \fIF\fP or \fIG\fP
.RE
.TP
.B "\-t" \fIbase\fP[\fIbyte\fP]
type of base: for memory output (default \fIbI\fP)
.RS
.TP
.B "base"
output number base: bits are converted to numbers of this base:
\fIa\fP = ASCII, \fIb\fP = binary, \fId\fP = decimal, \fIh\fP = hex,
\fIo\fP = octal
.TP
.B "byte"
byte width: number \fI1\fP to \fIword width\fP or
\fII\fP = full word width, \fIC\fP = 8, \fIS\fP = 16, \fIL\fP = 32 (default
\fIword width\fP, unless \fIASCII\fP where it is \fI8\fP). ASCII with less than 7 width is not allowed (is sensless)
.RE
.TP
.B "\-o" \fIfile\fP
output file: send to file (default \fIstdout\fP)
.SH ARGUMENTS
If an argument remains after option processing, it is assumed to be an
\fIfile name\fP, of the bitfile to be processed. Else a bitstream is expected
to come from \fIstdin\fP.
.SH ENVIRONMENT
.B "vd"
uses no environment variables.
.SH EXAMPLES
.TP
.B "vd pdp10.bit"
dumps \fIfull\fP pdp10.bit FPGA, 48*2*32*2 logic cells, at 1 line per cell
.TP
.B "vd -r 17L pdp10.bit"
dumps \fIone slice\fP of pdp10.bit, 32*2 logic cells and lines
.TP
.B "vd -rs 4-7/13-18 pdp10.bit"
dumps \fIrectangular section\fP of pdp10.bit, 4*2*6*2 logic cells and lines,
with \fIshort\fP format
.TP
.B "vd -rql 23R/14G pdp10.bit"
dumps \fIone single logic cell\fP of pdp10.bit, 1 single line, \fIquiet\fP
format, and \fIonly LUTs\fP. Produces an single hex number
.TP
.B "vd -re 23/14 pdp10.bit"
dumps \fIone single CLB configuration\fP of pdp10.bit, as bit pattern
.TP
.B "vd -re 23R/14G pdp10.bit"
dumps \fIsame single CLB\fP of pdp10.bit, as -re ignores slice and LUT in range
.TP
.B "vd -rm 2L/0-17 pdp10.bit"
dumps \fI1 memory of 16 words of 2*18bits\fP width out of pdp10.bit
.TP
.B "vd -rmq 2L/0-17 -t b6 pdp10.bit"
dumps above memory out of pdp10.bit, as \fI6bit bytes in binary\fP and in
\fIquiet\fP format
.TP
.B "vd -rmz 1/0-17 pdp10.bit"
dumps \fI1 zigzag memory\fP of 32 words of 2*16bits width out of pdp10.bit
.TP
.B "vd -rmzst 1/0-17 o9 pdp10.bit"
dumps above zigzag memory out of pdp10.bit, as \fI9bit bytes in octal, in
\fIshort\fP format
.SH BUGS
Due to the way base conversion is implemented (\fIsprintf()\fP on an
\fIulong\fP variable) the \fIbyte\fP width is not allowed to be larger than
\fI32\fP, unless \fItype\fP is binary (which requires no conversion).
.PP
Due to the way it is implemented (only one character) \fIASCII\fP mode will
ignore any part of an byte \fwider than I8\fP bits.
.SH SEE ALSO
presently none, later \fIvv(1)\fP, \fIvm\fP(1) and others
.SH HISTORY
Desire to see more about what is going on in an FPGA. A detailled history and
todo list can be seen in http://neil.franklin.ch/Projects/VirtexTools/Logfile
.SH AUTHOR
neil@franklin.ch, http://neil.franklin.ch/