# fpgadiag #
## SYNOPSIS ##
```console
fpgadiag [-m | --mode=] <mode> [-t | --target=] <target> [options]
```
## DESCRIPTION ##
Includes several tests to diagnose, test, and report on the FPGA hardware.
```<mode>``` chooses which test to run.
```<target>``` specifies the platform that runs the test.
```<target>``` can be either ```fpga``` or ```ase``` where ```ase```.
```<ase>``` is the abbreviation for Accelerator Simulation Environment.
The ```<mode>``` selects from the following tests:
**lpbk1**
This test runs a loopback test on the number of cachelines specified with
the ```BEGIN``` option. ```fpgadiag``` sets up source and destination buffers in
main memory. The FPGA then performs a ```memcpy``` from a source buffer to the
destination buffer, one cacheline at a time.
A cacheline is 64 bytes. When `BEGIN = END`, the test performs one iteration. When
`BEGIN = END + x`, the test performs `x` iterations. The first iteration consists
of copying `BEGIN` cachelines; the second iteration consists of copying
`BEGIN+1` cache lines. The third iteration consists of copying `BEGIN+2`
cache lines, and so on.
The latency is shown as the number of clock cycles.
When you specify `MULTI-CL`, you copy `MULTI-CL` cache lines at a time.
The WR-FENCE chooses on which virtual channel the WrFence occurs.
If you specify continuous mode with `--cont`, the program iterates
until the timeout specified in `TIMEOUT` completes.
**read**
This test performs reads. Use this test to measure read bandwidth.
**write**
This test performs writes. Use it to measure write bandwidth.
**trput**
This test measures both read and write bandwidth by performing 50% read and
50% write tests.
**sw**
This is a send-and-respond (ping-pong) test. One side sends data and
waits for response.
Each test requires a particular AF. Before running a test,
make sure the required AF is properly configured
on the platform.
* The lpbk1 test requires the nlb mode 0 AF.
* The trput test requires the nlb mode 3 AF.
* The sw test requires the nlb mode 7 AF. This AF is only available for the integrated FPGA platform.
You cannot run it on the PCIe accelerator card (PAC).
**fpgalpbk**
This enable/disable FPGA loopback.
**fpgastats**
This get fpga mac statistics.
**mactest**
This compare mac addresses that read from MAC ROM with mac addresses read from Host side.
## OPTIONS ##
### Common options ###
`--help, -h`
Print help information and exit.
`--target=, -t`
This switch specifies fpga (hardware) or ase (simulation). The default=fpga.
`--mode=, -m`
The test to run. The valid values are `lpbk1`, `read`,
`write`, `trput`, and `sw`.
`--config=, -c`
A configuration file in the JSON format that specifies options for a test.
If an option is specified both in the configuration file and on the command
line, the value in the configuration file takes precedence.
`--dsm-timeout-usec`
Timeout in microseconds for test completion. The test fails if not completed by
specified timeout. The default=1000000.
`--socket-id=, -s`
Socket ID encoded in FPGA Interface Manager (FIM). The default=0.
`--bus=, -B`
Bus number of the PCIe device. The default=0.
`--device=, -D`
Device number of the PCIe device. The default=0.
`--function=, -F`
Function number of the PCIe device. The default=0.
`--freq=, -T`
Clock frequency (in Hz) used for bandwidth calculation. The default=400000000 Hz (400 MHz).
```eval_rst
.. note::
This frequency is used only when the software cannot infer the frequency from the accelerator.
```
`--suppress-hdr, -S`
Suppress column headers for text output. The default=off.
`--csv, -V`
Comma separated value format. The default=off.
`--suppress-stats`
Suppress statistics output at the end of test. The default=off.
### **lpbk1** test options ###
`--guid=, -g`
AFU ID to enumerate. The default=D8424DC4-A4A3-C413-F89E-433683F9040B.
`--begin=B, -b`
1 <= B <= 65535. The default=1, B = number of cache lines.
`--end=E, -e`
1 <= E <= 65535. The default=B, B and E designate number of cache lines.
`--multi-cl=M, -u`
M can equal 1, 2, or 4. The default=1.
`--cont, -L`
Continuous mode. The default=off.
`--timeout-usec=, --timeout-msec=, --timeout-sec=, --timeout-min=, --timeout-hour=`
timeout for --cont mode. The default for all options is 0.
`--cache-policy=, -p`
Can be wrline-I, wrline-M, or wrpush-I The default=wrline-M.
`--cache-hint=, -i`
Can be rdline-I or rdline-S. The default=rdline-I.
`--read-vc=, -r`
Can be auto, vl0, vh0, vh1, random. The default=auto.
`--write-vc=, -w`
Can be auto, vl0, vh0, vh1, random. The default=auto.
`--wrfence-vc=, -f`
Can be auto, vl0, vh0, vh1. The default=auto.
### **read** test options ###
`--guid=, -g`
AFU ID to enumerate. The default=F7DF405C-BD7A-CF72-22F1-44B0B93ACD18.
`--begin=B, -b`
1 <= B <= 65535. The default=1, B = number of cache lines.
`--end=E, -e`
1 <= E <= 65535. The default=B, B and E designate number of cache lines.
`--multi-cl=M, -u`
M can equal 1, 2, or 4. The default=1.
`--strided-access=S, -a`
1<= S <= 64. The default=1.
`--cont, -L`
Continuous mode. The default=off.
`--timeout-usec=, --timeout-msec=, --timeout-sec=, --timeout-min=, --timeout-hour=`
timeout for --cont mode. The default for all options is 0.
`--cache-hint=, -i`
Can be rdline-I or rdline-S. The default=rdline-I.
`--warm-fpga-cache -H; --cool-fpga-cache -M`
Try to prime the cache with hits. The default=off. Try to prime the
cache with misses. The default=off.
`--cool-cpu-cache, -C`
Try to prime the cpu cache with misses. The default=off.
`--read-vc=, -r`
Can be auto, vl0, vh0, vh1, random. The default=auto
### **write** test options ###
`--guid=, -g`
AFU ID to enumerate. The default=F7DF405C-BD7A-CF72-22F1-44B0B93ACD18
`--begin=B, -b`
1 <= E <= 65535. The default=B, B and E designate number of cache lines.
`--multi-cl=M, -u`
M can equal 1, 2, or 4. The default=1.
`--strided-access=S, -a`
1<= S <= 64. The default=1.
`--cont, -L`
Continuous mode. The default=off.
`--timeout-usec=, --timeout-msec=, --timeout-sec=, --timeout-min=, --timeout-hour=`
timeout for --cont mode. The default for all options is 0.
`--cache-policy=, -p`
Can be wrline-I, wrline-M, or wrpush-I The default=wrline-M
`--warm-fpga-cache -H; --cool-fpga-cache -M`
Try to prime the cache with hits. The default=off. Try to prime the
cache with misses. The default=off.
`--cool-cpu-cache, -C`
Try to prime the cpu cache with misses. The default=off.
`--write-vc=, -w`
Can be auto, vl0, vh0, vh1, random. The default=auto.
`--wrfence-vc=, -f`
Can be auto, vl0, vh0, vh1, random. The default=`WRITE-VC`.
`--alt-wr-pattern, -l`
Alternate Write Pattern. The default=off.
### **trput** test options ###
`--guid=, -g`
AFU ID to enumerate. The default=F7DF405C-BD7A-CF72-22F1-44B0B93ACD18.
`--begin=B, -b`
1 <= B <= 65535. The default=1, B = number of cache lines.
`--end=E, -e`
1 <= E <= 65535. The default=B, B and E designate number of cache lines.
`--multi-cl=M, -u`
M can equal 1, 2, or 4. The default=1.
`--strided-access=S, -a`
1<= S <= 64. The default=1
`--cont, -L`
Continuous mode. The default=off.
`--timeout-usec=, --timeout-msec=, --timeout-sec=, --timeout-min=, --timeout-hour=`
timeout for --cont mode. The default for all options is 0.
`--cache-policy=, -p`
Can be wrline-I, wrline-M, or wrpush-I The default=wrline-M.
`--cache-hint=, -i`
Can be rdline-I or rdline-S. The default=rdline-I.
`--read-vc=, -r`
Can be auto, vl0, vh0, vh1, random. The default=auto.
`--write-vc=, -w`
Can be auto, vl0, vh0, vh1, random. The default=auto.
`--wrfence-vc=, -f`
Can be auto, vl0, vh0, vh1. The default=`WRITE-VC`.
### **sw** test options ###
`--guid=, -g`
AFU ID to enumerate. The default=7BAF4DEA-A57C-E91E-168A-455D9BDA88A3.
`--begin=B, -b`
1 <= B <= 65535. The default=1, B = number of cache lines.
`--end=E, -e`
1 <= E <= 65535. The default=B, B and E designate number of cache lines.
`--cache-policy=, -p`
Can be wrline-I, wrline-M, or wrpush-I. The default=wrline-M.
`--cache-hint= -i`
Can be rdline-I or rdline-S. The default=rdline-I.
`--read-vc=, -r`
Can be auto, vl0, vh0, vh1, random The default=auto.
`--write-vc=, -w`
Can be auto, vl0, vh0, vh1, random The default=auto.
`--wrfence-vc=, -f`
Can be auto, vl0, vh0, vh1. The default=`WRITE-VC`.
`--notice=, -N`
Can be poll or csr-write. The default=poll.
### **fpgalpbk** test options ###
`--enable`
Enable fpga phy loopback.
`--disable`
Disable fpga phy loopback.
`--direction`
Can be local, remote.
`--type`
Can be serial, precdr, postcdr.
`--side`
Can be line, host.
`--port`
0 <= port <= 7, the default is all.
### **mactest** test options ###
`--offset`
Read mac addresses from an offset, The default=0.
## EXAMPLES ##
This command starts a `lpbk1` test for the FPGA on bus `0x5e`. The test
copies 57535, 57536, 57537 ... up to 65535 cache lines, one line at a time.
The test prints output in the comma separated values (CSV) format with the
header suppressed.
```console
./fpgadiag --mode=lpbk1 --target=fpga -V --bus=0x5e --begin=57535
--end=65535 --cache-hint=rdline-I --cache-policy=wrpush-I --multi-cl=1
--write-vc=vl0 --read-vc=vh1 --wrfence-vc=auto
```
This command starts a `read` test on the FPGA located on bus `0xbe`. The test
reads 2045 cache lines in the continuous mode with a 15-second timeout period.
The reads use a strided pattern with a 10-byte stride length.
```console
./fpgadiag --mode=read --target=fpga -V --bus=0xbe --begin=2045 --cont
--timeout-sec=15 --cache-hint=rdline-I --multi-cl=1 -a=10
--read-vc=auto --wrfence-vc=auto
```
This command starts a `sw` test on the FPGA located on bus `0xbe`. The test
signals completion using a CSR write.
```console
./fpgadiag --mode=sw --target=fpga -V --bus=0xbe --begin=4 --end=8192
--cache-hint=rdline-I --cache-policy=wrline-I --notice=csr-write --write-vc=vl0
--wrfence-vc=auto --read-vc=random
```
This command enable a `fpgalpbk` on the FPGA located on bus `0xbe`.
```console
./fpgadiag -m fpgalpbk --bus 0xbe --enable --direction local --type postcdr
--side host
```
This command show `fpgastats` on the FPGA located on bus `0xbe`.
```console
./fpgadiag -m fpgastats --bus 0xbe
```
## TROUBLESHOOTING ##
When a test fails to run or gives errors, check the following:
* Is the Intel FPGA driver properly installed?
See [Installation Guide](/fpga-doc/docs/install_guide/installation_guide.html)
for driver installation instructions.
* Are FPGA port permissions set properly? Check the permission bits of the
port, for example, `/dev/intel-fpga-port-0`. You need READ and WRITE
permissions to run `fpgadiag` tests.
* Is hugepage properly configured on the system?
See [Installation Guide](/fpga-doc/docs/install_guide/installation_guide.html)
for hugepage configuration steps. In particular, `fpgadiag` requires a few 1 GB
pages.
* Is the required AFU loaded? See [DESCRIPTION](#description) for
information about what AFU the test requires.
* Are `--begin` and `--end` values set properly? `--end` must be larger
than the `--begin`. Also, `--begin` must be a multiple of the
`--multi-cl` value.
* The `--warm-fpga-cache` and `--cool-fpga-cache` options in the `read`
and `write` tests are mutually exclusive.
* The timeout options are only meaningful for the continuous mode
(with the `--cont` option).
## Revision History ##
| Date | Intel Acceleration Stack Version | Changes Made |
|:------|----------------------------|:--------------|
|2018.05.21| DCP 1.1 Beta (works with Quartus Prime Pro 17.1.1) | fpgadiag now reports the correct values for bandwidth. |