fpgadiag

SYNOPSIS

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).

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-number=, -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).

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 ddfault=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.

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.

./fpgadiag --mode=lpbk1 --target=fpga -SV --bus-number=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.

./fpgadiag --mode=read --target=fpga -SV --bus-number=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.

./fpgadiag --mode=sw --target=fpga -SV --bus-number=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

TROUBLESHOOTING

When a test fails to run or gives errors, check the following:

  • Is the Intel FPGA driver properly installed? See Installation Guide 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 for hugepage configuration steps. In particular, fpgadiag requires a few 1 GB pages.
  • Is the required AFU loaded? See 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.