From eb43f9017482b569b47c0c734b926ec2b9ffa853 Mon Sep 17 00:00:00 2001 From: "Bland, Lissy" Date: Thu, 8 Mar 2018 12:54:48 -0800 Subject: [PATCH] OPAE Tools Documentation Update for 0.13.1 (1.0 PRQ) (#308) (cherry picked from commit 8deeb64097f18c766e8c82abf989204ebd77cbfb) --- doc/src/fpga_tools/coreidle/coreidle.md | 10 +- doc/src/fpga_tools/fpgabist/fpgabist.md | 10 +- doc/src/fpga_tools/fpgaconf/fpgaconf.md | 9 +- doc/src/fpga_tools/fpgad/fpgad.md | 21 +-- doc/src/fpga_tools/fpgadiag/README.md | 123 ++++++++------- doc/src/fpga_tools/fpgaflash/fpgaflash.md | 18 ++- doc/src/fpga_tools/fpgainfo/fpgainfo.md | 55 ++++--- doc/src/fpga_tools/fpgamux/fpgamux.md | 26 ++-- doc/src/fpga_tools/fpgaport/fpgaport.md | 12 +- doc/src/fpga_tools/hssi_config/readme.md | 165 ++++++++++++--------- doc/src/fpga_tools/hssi_loopback/readme.md | 76 ++++++---- doc/src/fpga_tools/mmlink/mmlink.md | 39 +++-- doc/src/fpga_tools/packager/packager.md | 91 ++++++------ doc/src/fpga_tools/userclk/userclk.md | 28 +++- 14 files changed, 387 insertions(+), 296 deletions(-) diff --git a/doc/src/fpga_tools/coreidle/coreidle.md b/doc/src/fpga_tools/coreidle/coreidle.md index 6f5273c80dc7..358a763505c4 100644 --- a/doc/src/fpga_tools/coreidle/coreidle.md +++ b/doc/src/fpga_tools/coreidle/coreidle.md @@ -7,9 +7,9 @@ ## DESCRIPTION ## -coreidle parses the Accelerator Function Unit (AFU) metadata and extracts power information. coreidle calculates the FPGA power -and calculates the number of online and idle cores. It moves threads from idle cores to online cores. coreidle is only available -the Integrated FPGA Platform. You cannot run coreidle on the PCIe Accelerator Card (PAC). +```coreidle``` parses the Accelerator Function Unit (AFU) metadata and extracts power information. ```coreidle``` calculates +the FPGA power and calculates the number of online and idle cores. It moves threads from idle cores to online cores. +```coreidle``` is only available the Integrated FPGA Platform. You cannot run ```coreidle``` on the PCIe Accelerator Card (PAC). ## EXAMPLES ## @@ -20,9 +20,9 @@ the Integrated FPGA Platform. You cannot run coreidle on the PCIe Accelerator Ca ## OPTIONS ## -`-B,--bus` FPGA Bus number. +`-B,--bus` FPGA bus number. -`-D,--device` FPGA Device number. +`-D,--device` FPGA device number. `-F,--functio` FPGA function number. diff --git a/doc/src/fpga_tools/fpgabist/fpgabist.md b/doc/src/fpga_tools/fpgabist/fpgabist.md index 1a2db3393337..cbac274c9f80 100644 --- a/doc/src/fpga_tools/fpgabist/fpgabist.md +++ b/doc/src/fpga_tools/fpgabist/fpgabist.md @@ -6,20 +6,20 @@ fpgabist [-h] [-i device_id] [-b bus] [-d device] [-f function] [path_to_gbs1 pa ``` ## DESCRIPTION ## -The fpgabist tool performs self-diagnostic tests on supported FPGA platforms. +The ```fpgabist``` tool performs self-diagnostic tests on supported FPGA platforms. The tool accepts one or more Accelerator Function (AF) binaries from a predetermined set of AFs. Depending on the available binaries, the tool runs appropriate tests and reports hardware issues. -fpgabist always uses fpgainfo to report system information before running any hardware tests. +```fpgabist``` always uses ```fpgainfo``` to report system information before running any hardware tests. -Currently, fpgabist accepts the following AFs: +Currently, ```fpgabist``` accepts the following AFs: 1. nlb_mode_3 = host memory interface checking 2. dma = local memory interface checking The platform includes the AF files, but you can also compile the AFs from the source. -If there are multiple devices, use -b, -d, -f to specify the BDF for the specific device. If you do not specify a BDF, fpgabist tests all cards. +If there are multiple devices, use -b, -d, -f to specify the BDF for the specific device. ## POSITIONAL ARGUMENTS ## `[path_to_gbs1 path_to_gbs2 ...]` @@ -51,6 +51,6 @@ If there are multiple devices, use -b, -d, -f to specify the BDF for the specifi `fpgabist /dma_afu.gbs /nlb_3.gbs` - Runs fpgabist on any platforms in the system that match the default device ID. This command runs both the DMA and NLB_MODE_3 tests. + Runs ```fpgabist``` on any platforms in the system that match the default device ID. This command runs both the DMA and NLB_MODE_3 tests. diff --git a/doc/src/fpga_tools/fpgaconf/fpgaconf.md b/doc/src/fpga_tools/fpgaconf/fpgaconf.md index b5fb18297d4f..8d4e019e20b5 100644 --- a/doc/src/fpga_tools/fpgaconf/fpgaconf.md +++ b/doc/src/fpga_tools/fpgaconf/fpgaconf.md @@ -6,9 +6,8 @@ ## DESCRIPTION ## -fpgaconf configures the FPGA with the AF. It also checks the AF for compatibility with -the targeted FPGA and the FPGA Interface Manager (FIM). fpgaconf takes the -following arguments: +```fpgaconf``` configures the FPGA with the accelerator funciton (AF). It also checks the AF for compatibility with +the targeted FPGA and the FPGA Interface Manager (FIM). ```fpgaconf``` takes the following arguments: `-h, --help` @@ -40,9 +39,9 @@ following arguments: Socket number of the target FPGA. -fpgaconf enumerates available FPGA devices in the system and selects +```fpgaconf``` enumerates available FPGA devices in the system and selects compatible FPGAs for configuration. If more than one FPGA is -compatible with the AF, fpgaconf exits and asks you to be +compatible with the AF, ```fpgaconf``` exits and asks you to be more specific in selecting the target FPGAs by specifying a socket number or a PCIe BDF. diff --git a/doc/src/fpga_tools/fpgad/fpgad.md b/doc/src/fpga_tools/fpgad/fpgad.md index 8dec5d8c700e..3978bcec1b0b 100644 --- a/doc/src/fpga_tools/fpgad/fpgad.md +++ b/doc/src/fpga_tools/fpgad/fpgad.md @@ -5,14 +5,15 @@ `fpgad [--socket=] [--null-bitstream=]` ## DESCRIPTION ## -fpgad periodically monitors and reports the error status reflected in the device driver's error status sysfs files. -fpgad establishes the channel to communicate events to the OPAE application. fpgad programs a NULL bitstream -in response to an AP6 (power) event. fpgad is only available on the Integrated FPGA Platform. You cannot run -fpgad on the PCIe Accelerator Card (PAC). +```fpgad``` periodically monitors and reports the error status reflected in the device driver's error status sysfs files. +```fpgad``` establishes the channel to communicate events to the Open Programmable Accelerator Engine (OPAE) application. +```fpgad``` programs a NULL bitstream in response to an AP6 (power) event. ```fpgad``` is only available on the Integrated FPGA +Platform. You cannot run ```fpgad``` on the PCIe® Accelerator Card (PAC). -If your system does not support interrupts, you must run fpgad before the API calls `fpgaRegisterEvent` and `fpgaUnregisterEvent` can succeed. +If your system does not support interrupts, you must run ```fpgad``` before the API calls `fpgaRegisterEvent` and +`fpgaUnregisterEvent` can succeed. -Use SIGINT to stop fpgad. +Use SIGINT to stop ```fpgad```. `-d, --daemon` @@ -21,22 +22,22 @@ Use SIGINT to stop fpgad. `-D, --directory ` When running in daemon mode, run from the specified directory. - If omitted when daemonizing, /tmp is used. + If omitted when daemonizing, `fpgad` uses /tmp. `-l, --logfile ` When running in daemon mode, send output to file. When not in daemon mode, the output goes to stdout. - If omitted when daemonizaing, /tmp/fpgad.log is used. + If omitted when daemonizaing, fpgad uses /tmp/fpgad.log. `-p, --pidfile ` When running in daemon mode, write the daemon's process id to a file. - If omitted when daemonizing, /tmp/fpgad.pid is used. + If omitted when daemonizing, fpgad uses /tmp/fpgad.pid. `-m, --umask ` When running in daemon mode, use the mode value as the file mode creation mask passed to umask. - If omitted when daemonizing, 0 is used. + If omitted when daemonizing, fpgad uses 0. `-s, --socket ` diff --git a/doc/src/fpga_tools/fpgadiag/README.md b/doc/src/fpga_tools/fpgadiag/README.md index 6c3dfa0a9c1b..cb51f37631e9 100644 --- a/doc/src/fpga_tools/fpgadiag/README.md +++ b/doc/src/fpga_tools/fpgadiag/README.md @@ -9,57 +9,57 @@ fpgadiag [-m | --mode=] [-t | --target=] [options] ## DESCRIPTION ## Includes several tests to diagnose, test, and report on the FPGA hardware. -`` chooses which test to run. -`` specifies the platform that runs the test. -`` can be either `fpga` or `ase` where `ase` stands for -Accelerator Simulation Environment. +`````` chooses which test to run. +`````` specifies the platform that runs the test. +`````` can be either ```fpga``` or ```ase``` where ```ase```. +`````` is the abbreviation for Accelerator Simulation Environment. -The `` selects from the following tests: +The `````` 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. +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+3` - cache lines, and so on. +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. +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 what virtual channel the WrFence occurs on. +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. +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. +This test performs reads. Use this test to measure read bandwidth. **write** - This test performs writes. Use it to measure write bandwidth. +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. +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. +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 @@ -151,9 +151,7 @@ on the platform. `--timeout-usec=, --timeout-msec=, --timeout-sec=, --timeout-min=, --timeout-hour=` - timeout for --cont mode (microseconds portion default=0; milliseconds - portion default=0; seconds portion default=1; minutes portion default=0; - hours portion default=0) + timeout for --cont mode. The default for all options is 0. `--cache-policy=, -p` @@ -179,23 +177,23 @@ on the platform. ### **read** test options ### `--guid=, -g` - AFU ID to enumerate. The default=F7DF405C-BD7A-CF72-22F1-44B0B93ACD18 + 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 + 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 + 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 + M can equal 1, 2, or 4. The default=1. `--strided-access=S, -a` - 1<= S <= 64. The default=1 + 1<= S <= 64. The default=1. `--cont, -L` @@ -203,22 +201,20 @@ on the platform. `--timeout-usec=, --timeout-msec=, --timeout-sec=, --timeout-min=, --timeout-hour=` - timeout for --cont mode (microseconds portion default=0; milliseconds - portion default=0; seconds portion default=1; minutes portion default=0; - hours portion default=0) + 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 + Can be rdline-I or rdline-S. The default=rdline-I. `--warm-fpga-cache -H; --cool-fpga-cache -M` - Attempt to prime the cache with hits. The default=off, Attempt to prime the + Try to prime the cache with hits. The default=off. Try to prime the cache with misses. The default=off. `--cool-cpu-cache, -C` - Attempt to prime the cpu cache with misses. The default=off. + Try to prime the cpu cache with misses. The default=off. `--read-vc=, -r` @@ -232,7 +228,7 @@ on the platform. `--begin=B, -b` - 1 <= E <= 65535. The default=B, B and E designate number of cache lines + 1 <= E <= 65535. The default=B, B and E designate number of cache lines. `--multi-cl=M, -u` @@ -240,7 +236,7 @@ on the platform. `--strided-access=S, -a` - 1<= S <= 64. The default=1 + 1<= S <= 64. The default=1. `--cont, -L` @@ -248,9 +244,7 @@ on the platform. `--timeout-usec=, --timeout-msec=, --timeout-sec=, --timeout-min=, --timeout-hour=` - timeout for --cont mode (microseconds portion default=0; milliseconds - portion default=0; seconds portion default=1; minutes portion default=0; - hours portion default=0) + timeout for --cont mode. The default for all options is 0. `--cache-policy=, -p` @@ -258,20 +252,20 @@ on the platform. `--warm-fpga-cache -H; --cool-fpga-cache -M` - Attempt to prime the cache with hits. The default=off. Attempt to prime the + Try to prime the cache with hits. The default=off. Try to prime the cache with misses. The default=off. `--cool-cpu-cache, -C` - Attempt to prime the cpu cache with misses. The default=off. + Try to prime the cpu cache with misses. The default=off. `--write-vc=, -w` - Can be auto, vl0, vh0, vh1, random. The default=auto + Can be auto, vl0, vh0, vh1, random. The default=auto. `--wrfence-vc=, -f` - Can be auto, vl0, vh0, vh1, random. The default=`WRITE-VC` + Can be auto, vl0, vh0, vh1, random. The default=`WRITE-VC`. `--alt-wr-pattern, -l` @@ -285,11 +279,11 @@ on the platform. `--begin=B, -b` - 1 <= B <= 65535. The default=1, B = number of cache lines + 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 + 1 <= E <= 65535. The default=B, B and E designate number of cache lines. `--multi-cl=M, -u` @@ -305,29 +299,27 @@ on the platform. `--timeout-usec=, --timeout-msec=, --timeout-sec=, --timeout-min=, --timeout-hour=` - timeout for --cont mode (microseconds portion default=0; milliseconds - portion default=0; seconds portion default=1; minutes portion default=0; - hours portion default=0) + 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 + 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 + Can be rdline-I or rdline-S. The default=rdline-I. `--read-vc=, -r` - Can be auto, vl0, vh0, vh1, random. The default=auto + Can be auto, vl0, vh0, vh1, random. The default=auto. `--write-vc=, -w` - Can be auto, vl0, vh0, vh1, random. The default=auto + Can be auto, vl0, vh0, vh1, random. The default=auto. `--wrfence-vc=, -f` - Can be auto, vl0, vh0, vh1. The default=`WRITE-VC` + Can be auto, vl0, vh0, vh1. The default=`WRITE-VC`. ### **sw** test options ### @@ -337,19 +329,19 @@ on the platform. `--begin=B, -b` - 1 <= B <= 65535. The default=1, B = number of cache lines + 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 + 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 + 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 + Can be rdline-I or rdline-S. The ddfault=rdline-I. `--read-vc=, -r` @@ -371,7 +363,8 @@ on the platform. ## 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 CSV format with the header suppressed. +The test prints output in the comma separated values (CSV) format with the +header suppressed. ```console ./fpgadiag --mode=lpbk1 --target=fpga -SV --bus-number=0x5e --begin=57535 --end=65535 --cache-hint=rdline-I --cache-policy=wrpush-I --multi-cl=1 @@ -411,8 +404,8 @@ 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 no -smaller than the `--begin`. Also, `--begin` must be a multiple of the +* 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. diff --git a/doc/src/fpga_tools/fpgaflash/fpgaflash.md b/doc/src/fpga_tools/fpgaflash/fpgaflash.md index 99b7b26e20c6..f2705d427252 100644 --- a/doc/src/fpga_tools/fpgaflash/fpgaflash.md +++ b/doc/src/fpga_tools/fpgaflash/fpgaflash.md @@ -13,19 +13,25 @@ If there are multiple devices in the system, fpgaflash must specify a BDF to sel ## POSITIONAL ARGUMENTS ## `{user, factory}` - type of flash programming + Specifies the type of flash programming. - A user update only reprograms the user image in flash. + `user` + + Only reprograms the user image in flash. - A factory update reprograms the entire flash. A catastrophic failure during a factory update such as a power outage requires a USB cable and quartus_pgm to recover. + `factory` + + Reprograms the entire flash. A catastrophic failure during a factory update such as a power outage + requires a USB cable and `quartus_pgm` to recover. `file` - rpd file to program into flash. +Specifies the Raw Programming Data File (rpd) to program into flash. `bdf` - BDF of device to program such as 04:00.0 or 0000:04:00.0. This flag is optional when there is a single device in the system. +Specifies the bus, device and function (BDF) of device to program such as 04:00.0 or 0000:04:00.0. This flag +is optional when there is a single device in the system. ## OPTIONAL ARGUMENTS ## @@ -37,4 +43,4 @@ If there are multiple devices in the system, fpgaflash must specify a BDF to sel `fpgaflash user new_image.rpd 0000:04:00.0` - Programs new_image.rpd to flash of device with BDF 0000:04:00.0. +Programs new_image.rpd to flash of device with BDF 0000:04:00.0. diff --git a/doc/src/fpga_tools/fpgainfo/fpgainfo.md b/doc/src/fpga_tools/fpgainfo/fpgainfo.md index 7575f3da9736..25fb0c4b82e6 100644 --- a/doc/src/fpga_tools/fpgainfo/fpgainfo.md +++ b/doc/src/fpga_tools/fpgainfo/fpgainfo.md @@ -2,57 +2,64 @@ ## SYNOPSIS ## ```console -fpgainfo [-h | --help] [-b ] [-d ] [-f ] [] +fpgainfo [-h | --help] [] ``` ## DESCRIPTION ## -fpgainfo displays FPGA information derived from sysfs files. The command argument is one of the following: errors, power, or temp. -Some commands may also have other arguments or options that control the behavior. +fpgainfo displays FPGA information derived from sysfs files. The command argument is one of the following: +`errors`, `power`, `temp`, `port` or `fme`. +Some commands may also have other arguments or options that control their behavior. -For systems with multiple devices, specify the BDF of the target device with -b, -d and -f. +For systems with multiple FPGA devices, you can specify the BDF to limit the output to the FPGA resource +with the corresponding PCIe configuration. If not specified, information displays for all resources for +the given command. ### FPGAINFO COMMANDS ## `errors` - Show/clear errors of an FPGA resource that the first argument specifies. - fpgainfo displays information in human readable form. +Show/clear errors of an FPGA resource that the first argument specifies. +`fpgainfo` displays information in human readable form. `power` - Show total the power in watts that the FPGA hardware consumes. +Show total the power in watts that the FPGA hardware consumes. `temp` - Show FPGA temperature values in degrees Fahrenheit. + Show FPGA temperature values in degrees Fahrenheit. `port` - Shows information about the port such as the AFU ID of currently loaded AFU. +Shows information about the port such as the AFU ID of currently loaded AFU. `fme` - Show information about the FPGA platform such as the FPGA Interface Manager (FIM) ID. +Show information about the FPGA platform such as the FPGA Interface Manager (FIM) ID. ## OPTIONAL ARGUMENTS ## `--help, -h` - Prints help information and exit. +Prints help information and exit. + +## COMMON ARGUMENTS ## +The following arguments are common to all commands and are optional. `-b, --bus` - PCIe bus number of the target FPGA. +PCIe bus number of resource. + `-d, --device` - PCIe device number of the target FPGA. +PCIe device number of resource. `-f, --function` - PCIe function number of the target FPGA. +PCIe function number of resource. -`--clear, -c` +`--json` - Clear errors for the given FPGA resource. +Display information as JSON string. ### ERRORS ARGUMENTS ### The first argument to the `errors` command specifies the resource type. It must be one of the following: @@ -60,15 +67,19 @@ The first argument to the `errors` command specifies the resource type. It must `fme` - Show/clear FME errors. + Show/clear FME errors. `port` - Show/clear PORT errors. + Show/clear PORT errors. `all` - Show/clear errors for all resources. +Show/clear errors for all resources. + +`--clear, -c` + +Clear errors for the given FPGA resource. ## EXAMPLES ## @@ -82,7 +93,7 @@ This command shows the current temperature reading: ./fpgainfo temp ``` -This command shows FME resource errors +This command shows FME resource errors: ```console ./fpgainfo errors fme ``` @@ -90,3 +101,7 @@ This command clears all errors on all resources: ```console ./fpgainfo errors all -c ``` +This command shows information of the FME on bus 0x5e +```console +./fpgainfo fme -b 0x5e +``` diff --git a/doc/src/fpga_tools/fpgamux/fpgamux.md b/doc/src/fpga_tools/fpgamux/fpgamux.md index 4053129255a1..9c2a1dba4ae2 100644 --- a/doc/src/fpga_tools/fpgamux/fpgamux.md +++ b/doc/src/fpga_tools/fpgamux/fpgamux.md @@ -7,10 +7,10 @@ fpgamux [-h] [-S|--socket-id SOCKET_ID] [-B|--bus-number BUS] [-D|--device DEVIC ``` ## DESCRIPTION ## -fpgamux tests multiple AFUs that are synthesized into a single AFU along with -the CCIP-MUX BBB (basic building block). The CCIP-MUX uses the upper bits in the MMIO addresses to route MMIO -reads and writes to the AFU running on the corresponding CCIP-MUX port. fpgamux uses a configuration file that -lists the software components and correct configuration. fpgamux only runs on the Integrated FPGA Platform. +```fpgamux``` tests multiple AFUs that are synthesized into a single AFU along with +the CCIP-MUX basic building block (BBB). The CCIP-MUX uses the upper bits in the MMIO addresses to route MMIO +reads and writes to the AFU running on the corresponding CCIP-MUX port. ```fpgamux``` uses a configuration file that +lists the software components and correct configuration. ```fpgamux``` only runs on the Integrated FPGA Platform. You cannot run it on the PCIe accelerator card (PAC). .. note:: @@ -24,26 +24,32 @@ You cannot run it on the PCIe accelerator card (PAC). ## OPTIONS ## `-S SOCKET_ID, --socket-id SOCKET_ID` + socket id of FPGA resource. `-B BUS, --bus BUS` + bus id of FPGA resource. `-D DEVICE, --device DEVICE` - device id of FPGA resource. + + The device id of FPGA resource. `-F FUNCTION, --function FUNCTION` - function id of FPGA resource. + + The function id of FPGA resource. `-G, --guid` - specifies the GUID to use for the AFC enumeration. + + Specifies the GUID to use for the AFC enumeration. `-m, --muxfile ` - The path to the fpgamux configuration file. This file must be in JSON format following the - schema described below. + +The path to the ```fpgamux``` configuration file. This file must be in JSON format following the +schema described below. ## CONFIGURATION ## -fpgamux uses a configuration file (in JSON format) to determine what software components to instantiate and +```fpgamux``` uses a configuration file (in JSON format) to determine what software components to instantiate and how to configure them to work with the AFUs. The schema includes the following elements: ``` diff --git a/doc/src/fpga_tools/fpgaport/fpgaport.md b/doc/src/fpga_tools/fpgaport/fpgaport.md index d66e9a76908a..200df66f1056 100644 --- a/doc/src/fpga_tools/fpgaport/fpgaport.md +++ b/doc/src/fpga_tools/fpgaport/fpgaport.md @@ -6,7 +6,7 @@ fpgaport [-h] {assign,release} device port ``` ## DESCRIPTION ## -The fpgaport enables and disables virtualization. It assigns +The ```fpgaport``` enables and disables virtualization. It assigns and releases control of the port to the virtual function (VF). By default, the driver assigns the port to the physical function (PF) in the non-virtualization use case. @@ -18,23 +18,23 @@ assigns the port to the physical function (PF) in the non-virtualization use cas `device` - The FPGA device being targeted with this action. +The FPGA device being targeted with this action. `port` - The number of the port. +The number of the port. ## OPTIONAL ARGUMENTS ## `-h, --help` - Print usage information. +Print usage information. ## EXAMPLE ## `fpgaport release /dev/intel-fpga-fme.0 0` - Release port 0 from physical function control. +Release port 0 from physical function control. `fpgaport assign /dev/intel-fpga-fme.0 0` - Assign port 0 to physical function control. +Assign port 0 to physical function control. diff --git a/doc/src/fpga_tools/hssi_config/readme.md b/doc/src/fpga_tools/hssi_config/readme.md index de44f861294e..a638cadb12ce 100644 --- a/doc/src/fpga_tools/hssi_config/readme.md +++ b/doc/src/fpga_tools/hssi_config/readme.md @@ -1,9 +1,9 @@ # hssi_config # ## Synopsis ## -hssi_config reads or writes HSSI registers on either on an Intel FPGA using the +```hssi_config``` reads or writes HSSI registers on either on an Intel® FPGA using the FPGA Interface Manager (FIM) or on an HSSI retimer card attached to the board. -hssi_config is only available for the Integrated FPGA Platform. You cannot run it +```hssi_config``` is only available for the Integrated FPGA Platform. You cannot run it on the PCIe accelerator card (PAC). ## Usage ## @@ -27,95 +27,97 @@ The first argument is the command and any additional arguments are command argum The following options and commands are available: ### Options ### + `[--resource|-r ` - The resource path in the sysfs psuedo-filesystem. - Example: +The resource path in the sysfs psuedo-filesystem. +Example: `/sys/devices/pci0000\:5e/0000\:5e\:00.0/resource0` `[--socket-id 0|1]` - The socket id of the target FPGA. - Required on two-socket systems to differentiate between the two possible target FPGAs. +The socket id of the target FPGA. +Required on two-socket systems to differentiate between the two possible target FPGAs. ### Commands ### `dump [outfile.csv] [--input-file inputfile.csv]` - Dump registers to stdout or to a file, if provided. hssi_config has a built-in set of registers to - dump. The first argument is the path to a file to write. The command dumps to stdout if you do not - specify a file name. Use the --input-file option to specify a different set of registers. +Dump registers to stdout or to a file, if provided. ```hssi_config``` has a built-in set of registers to +dump. The first argument is the path to a file to write. The command dumps to stdout if you do not +specify a file name. Use the --input-file option to specify a different set of registers. `load [inputfile.csv] [--c-header]` - Load a set of register values from either stdin or an input file if provided. The first argument - is the path to a file containing the registers to load. Loads from stdin if omitted. +Load a set of register values from either stdin or an input file, if provided. The first argument +is the path to a file containing the registers to load. Loads from stdin if omitted. - Use --c-header to generate a C header file with an array of 64-bit numbers to write to the HSSI_CTRL register. - This header file can substitute for the input file. - NOTE: You must perform the acknowledge routine after each write. +Use --c-header to generate a C header file with an array of 64-bit numbers to write to the +```HSSI_CTRL``` register. This header file can substitute for the input file. +NOTE: You must perform the acknowledge routine after each write. `read lane(0-15) reg-address` - Read from a single XCVR (transceiver) register. - The first command argument is the XCVR lane. Use -1 to specify a read from all lanes. - The second argument is the XCVR address (offset). +Read from a single XCVR (transceiver) register. +The first command argument is the XCVR lane. Use -1 to specify a read from all lanes. +The second argument is the XCVR address (offset). `write lane(0-15) reg-address value` - Write to a single XCVR register. - The first argument is the XCVR lane. - The second argument is the XCVR address(offset). - The third argument is the value to write to the register. +Write to a single XCVR register. +The first argument is the XCVR lane. +The second argument is the XCVR address(offset). +The third argument is the value to write to the register. `rread device(0x30, 0x32, 0x34, 0x36) channel(0-3) address` - Read from a single retimer register. - The first argument is the I2C device address. - The second argument is the channel. - The third argument is the register address (or I2C byte address). +Read from a single retimer register. +The first argument is the I2C device address. +The second argument is the channel. +The third argument is the register address (or I2C byte address). `rwrite device(0x30, 0x32, 0x34, 0x36) channel(0-3) address value` - Write to a single retimer register. - The first argument is the I2C device address. - The second argument is the channel. - The third argument is the register address (or I2C byte address). - The fourth argument is the value to write. +Write to a single retimer register. +The first argument is the I2C device address. +The second argument is the channel. +The third argument is the register address (or I2C byte address). +The fourth argument is the value to write. `iread instance (0,1) device-addr byte-address byte-count` - Read from a device on the I2C bus. - The first argument is the I2C controller instance (0 or 1). - The second argument is the device address to read from. - The third argument is the byte address of the register to read from the device. - The fourth argument is the number of bytes to read. +Read from a device on the I2C bus. +The first argument is the I2C controller instance (0 or 1). +The second argument is the device address to read from. +The third argument is the byte address of the register to read from the device. +The fourth argument is the number of bytes to read. `iwrite instance (0,1) device-addr byte-address byte1 [byte2 [byte3...]]` - Write to a device on the I2C bus. - The first argument is the I2C controller instance (0 or 1). - The second argument is the device address to read from. - The third argument is the byte address of the register to read from the device. - All subsequent arguments are the bytes to write to the device. +Write to a device on the I2C bus. +The first argument is the I2C controller instance (0 or 1). +The second argument is the device address to read from. +The third argument is the byte address of the register to read from the device. +All subsequent arguments are the bytes to write to the device. `test (rd|rw) inputfile.csv [--acktimes]` - Perform built-in test for reading or writing XCVR registers. - The first argument is the path to a file containing the registers to test. - +Perform built-in test for reading or writing XCVR registers. +The first argument is the path to a file containing the registers to test. ## Overview ## -hssi_config is a utility that reads or writes hssi equalization parameters stored in either + +The ```hssi_config``` utility reads or writes hssi equalization parameters stored in either the tranceiver (XCVR) registers or the registers of the retimer on the I2C bus. To access registers, -the hssi controller writes to the HSSI_CTRL register and reads from the HSSI_STAT -register in the the FME (FPGA Management Engine). These two registers implement the HSSI AUX bus -mailbox protocol to access devices on other buses. Because hssi_config maps the FME MMIO space directly, -the FPGA driver is not required. +the hssi controller writes to the ```HSSI_CTRL``` register and reads from the ```HSSI_STAT``` +register in the the FPGA Management Engine (FME). These two registers implement the HSSI AUX bus +mailbox protocol to access devices on other buses. Because ```hssi_config``` maps the FME MMIO +space directly, the FPGA driver is not required. + +## Locating the FME Device ## -## Locating the FME device ## -The FME (FPGA Management Engine) reads and writes the HSSI_CTRL and HSSI_STAT registers on the NIOS device. +The FME reads and writes the ```HSSI_CTRL``` and ```HSSI_STAT``` registers on the NIOS device. The FME maps the MMIO address space of the FME identified by its resource in the sysfs psuedo-filesystem -in Linux operating systems. To identify resource paths, use the lspci utility to query for Intel +in Linux operating systems. To identify resource paths, use the ```lspci``` utility to query for Intel devices with device id of bcc0. Example: @@ -137,13 +139,15 @@ use a resource path as follows: `/sys/devices/pci0000\:5e/0000\:5e\:00.0/resource0` -## CSV file format ## -Any CSV file parsed by hssi_config must meet have at least four columns. The following table provides the column specifications: +## CSV File Format ## + +Any CSV file parsed by ```hssi_config``` must meet have at least four columns. The following table provides +the column specifications: | Column | Name | Description | |:------:|-----------------------------|----------------------------------------------------------------------------------------------| -| 1 | Register type. | Can be either FPGA_RX, FPGA_TX, RTMR_RX, RTMR_TX (or their corresponding numeric values, 1-4).| +| 1 | Register type. | Can be either ```FPGA_RX```, ```FPGA_TX```, ```RTMR_RX```, ```RTMR_TX``` (or their corresponding numeric values, 1-4).| | 2 | Lane or Channel | 0-15 for XCVR lanes on FPGA, 0-3 for retimer channels. -1 to designate all lanes or channels.| | 3 | Device address (on I2C bus) | Only applies to retimer registers. 0 - 3, -1 to designate all devices. | | 4 | Register address (or offset)| Examples: 0x213, 0x100. | @@ -151,9 +155,10 @@ Any CSV file parsed by hssi_config must meet have at least four columns. The fol -## Examples of commands ## +## Examples of Commands ## + +### Dumping Registers ### -### Dumping registers ### Dump default register set to stdout: `>hssi_config dump` @@ -166,7 +171,8 @@ Dump to an output file, data.csv, Registers specified in an input file, regspec. `>hssi_config dump data.csv --input-file regspec.csv` -#### Reading single registers #### +#### Reading Single Registers #### + Read register from XCVR at 0x2e1 on lane 0: `>hssi_config read 0 0x2e1` @@ -175,7 +181,8 @@ Read register 0x109 from retimer on channel 0, device 0x30, channel 1: `>hssi_config rread 0 0x30 0x109` -### Loading registers ### +### Loading Registers ### + Load registers specified in an input file called data.csv: `>hssi_config load data.csv` @@ -191,7 +198,8 @@ FPGA_RX,3,-1,0x213,0 ``` -#### Writing single registers #### +#### Writing Single Registers #### + Write 1 to XCVR register at 0x2e1 on lane 0: `>hssi_config write 0 0x2e1 1` @@ -200,18 +208,29 @@ Read register 0x109 from retimer on channel 0, device 0x30, channel 1: `>hssi_config rread 0 0x30 0x109` -## Testing HSSI read and write ## -The `test` command tests read or read and write operations on the XCVR registers. -The first argument to test must be either rd or rw and the second argument is the path to a file -containing the set of registers to test. The rd command reads all the registers. For rw, +## Testing HSSI Read and Write ## + + +`> test (rd|rw) register-file.csv [--acktimes]` + +`rd|wr` + +Specifies either a `rd` or `wr` of transceiver registers. For writes, every register in the file is read from and written to in the following sequence: -1. Read the register, save the value -2. Write 1 to the register -3. Read the register, verify that the register value is 1 -4. Write 0 to the register -5. Read the register, verify that the register value is 0 -6. Write the original value to the register -7. Read the register, assert it is the original value - -The command line option --acktimes indicates that the time spent in the ack routine should -be measured. When meaured, a summary of ack times will be printed out. + + 1. Read the register, save the value + 2. Write 1 to the register + 3. Read the register, verify that the register value is 1 + 4. Write 0 to the register + 5. Read the register, verify that the register value is 0 + 6. Write the original value to the register + 7. Read the register, assert it is the original value + +`register=file.csv` + +Specifies the path to a file containing the set of registers to test. + +`--acktimes ` + +Specifies the time spent in the `ack` routine. When meaured, a summary of ack times prints +to stdout. This argument is optional. diff --git a/doc/src/fpga_tools/hssi_loopback/readme.md b/doc/src/fpga_tools/hssi_loopback/readme.md index be83b553ca85..13e072f8ee02 100644 --- a/doc/src/fpga_tools/hssi_loopback/readme.md +++ b/doc/src/fpga_tools/hssi_loopback/readme.md @@ -10,79 +10,97 @@ _hssi_loopback_ - Software utility to run HSSI loopback tests on FPGA [send [ [] [--packet-count|-c ] [--packet-delay|-d ] [--packet-length|-l ]] |status [clear] | stop | readmacs` ## DESCRIPTION ## -The hssi_loopback utility works in conjunction with a packet generator accelerator function unit (AFU) -to test HSSI (high-speed serial interface) cards. The hssi_loopback utility tests both external and internal loopbacks. -hssi_loopback runs an external loopback test when the command line arguments include both source and destination ports. hssi_loopback runs an internal loopback test when command line argurments include a single port. hssi_loopback only runs on the Integrated FPGA -Platform. You cannot run it on the PCIe accelerator card (PAC). + +The ```hssi_loopback``` utility works in conjunction with a packet generator accelerator function unit (AFU) +to test high-speed serial interface (HSSI) cards. The ```hssi_loopback``` utility tests both external and internal loopbacks. +```hssi_loopback``` runs an external loopback test when the command line arguments include both source and destination ports. +```hssi_loopback``` runs an internal loopback test when command line argurments include a single port. ```hssi_loopback``` +only runs on the Intel Xeon with Arria 10 FPGA. You cannot run it on the Intel PAC (programmable accelerator card). _NOTE_: The following limitations apply to the current version of hssi_loopback: * For the external loopback the two port arguments can be the same. For the e10 design, the ports should be the same. -* The hssi_loopback test supports only the e40 and e10 E2E AFUs. The e10 E2E AFU tests HSSI with a retimer card. -* The hssi_loopback test uses the control and status registers (CSRs) defined in the AFU. +* The ```hssi_loopback``` test supports only the e40 and e10 E2E AFUs. The e10 E2E AFU tests HSSI with a retimer card. +* The ```hssi_loopback``` test uses the control and status registers (CSRs) defined in the AFU. ## OPTIONS ## `-S SOCKET_ID, --socket-id SOCKET_ID` - Socket id of FPGA resource. + + Socket ID FPGA resource. `-B BUS, --bus BUS` - Bus id of FPGA resource. + +Bus ID of FPGA resource. `-D DEVICE, --device DEVICE` - Device id of FPGA resource. + +Device ID of FPGA resource. `-F FUNCTION, --function FUNCTION` - Function id of FPGA resource. + +Function ID of FPGA resource. `-G, --guid` - specifies guid for the AFC enumeration. + +Specifies guid for the AFC enumeration. `-m, --mode` - One of the following: [`auto`, `e40`, `e10] - `auto` is the default and indicates that the software runs the mode based on the - first acclerator functional context (AFC) it enumerates. + +One of the following: [`auto`, `e40`, `e10`] +`auto` is the default and indicates that the software runs the mode based on the first acclerator functional +context (AFC) it enumerates. `-t, --timeout` - Timeout (in seconds) before the application terminates in continous mode. Continuous mode is the default - when the number of packets is not specified. + +Timeout (in seconds) before the application terminates in continous mode. Continuous mode is the default +when you do not specify the number of packets. `-y, --delay` - Delay (in seconds) between printing out a simple status line. Default is 0.100 seconds (100 milliseconds). + +Delay (in seconds) between printing out a simple status line. Default is 0.100 seconds (100 milliseconds). `-c, --packet-count` - The number of packets to send. + +The number of packets to send. `-d, --packet-delay` - The delay in between packets. This delay is the number of 100 MHz clock cycles, roughly 10 nanoseconds. + +The delay in between packets. This delay is the number of 100 MHz clock cycles, roughly 10 nanoseconds. `-s, --packet-size` - The packet size to send. The minimum is 46 bytes and the maximum is 1500 bytes. The default is 46 bytes. + +The packet size to send. The minimum is 46 bytes and the maximum is 1500 bytes. The default is 46 bytes. ## COMMANDS ## `send [] [--packet-count|-c ] [--packet-delay|-d ] [--packet-length|-l ]` - Send packets from one port to the other. If the command line does not specify a destination port, the test runs an internal - loopback. Otherwise, the test runs an external loopback from the source port to the destination port. + +Send packets from one port to the other. If the command line does not specify a destination port, the test runs an internal +loopback. Otherwise, the test runs an external loopback from the source port to the destination port. `status [clear]` - Read and interpret the status registers and print to the screen. - `clear` clears the status registers. + +Read and interpret the status registers and print to the screen. `clear` clears the status registers. `stop` - Issue a stop command to all Ethernet controllers in the AFU. + +Issue a stop command to all Ethernet controllers in the AFU. `readmacs` - Read and display the port MAC addresses. An EEPROM stores the MAC addresses. + +Read and display the port MAC addresses. An EEPROM stores the MAC addresses. ## EXIT CODES ## - 0 Success - Number of packets received are equal to the number of packets sent and no errors + +0 Success - Number of packets received are equal to the number of packets sent and no errors are reported. - -1 Loopback failure - Either number of packets does not match or the test detected errors. +-1 Loopback failure - Either number of packets does not match or the test detected errors. - -2 Errors parsing arguments. +-2 Errors parsing arguments. ## EXAMPLES ## + Read the MAC addresses of the AFU loaded on bus 0x5e: ```sh diff --git a/doc/src/fpga_tools/mmlink/mmlink.md b/doc/src/fpga_tools/mmlink/mmlink.md index 6ca03152c4ad..14499cf47ede 100644 --- a/doc/src/fpga_tools/mmlink/mmlink.md +++ b/doc/src/fpga_tools/mmlink/mmlink.md @@ -1,36 +1,49 @@ # mmlink # -## SYNOPSIS ## +## Synopsis ## `mmlink [-B ] [-D ] [-F ] [-S ] [-P ] [-I ]` -## DESCRIPTION ## +## Description ## The Remote Signal Tap logic analyzer provides real-time hardware debugging for the Accelerator Function Unit (AFU). -It provides a signal trace capability that the Quartus Prime software adds to the AFU. -The Remote Signal Tap logic analyzer provides access to the RST part of the Port MMIO space and then runs the remote protocol. -## EXAMPLES ## +It provides a signal trace capability that the Quartus Prime software adds to the AFU. The Remote Signal Tap logic +analyzer provides access to the Remote Signal Tap part of the Port MMIO space and then runs the remote protocol. + +## Examples ## `./mmlink -B 0x5e -P 3333` MMLink app starts and listens for connection. -## OPTIONS ## +## Options ## + +`-B,--bus` + +FPGA Bus number. + +`-D,--device` + +FPGA Device number. + +`-F,--function` + +FPGA function number. -`-B,--bus` FPGA Bus number. +`-S,--socket` -`-D,--device` FPGA Device number. +FPGA socket number. -`-F,--functio` FPGA function number. +`-P,--port` -`-S,--socket` FPGA socket number. +TCP port number. -`-P,--port` TCP port number. +`-I,--ip ` -`-I,--ip ` IP address of FPGA system. +IP address of FPGA system. -## NOTES ## +## Notes ## Driver privilege: diff --git a/doc/src/fpga_tools/packager/packager.md b/doc/src/fpga_tools/packager/packager.md index 427e0f7ed978..352704be2afd 100644 --- a/doc/src/fpga_tools/packager/packager.md +++ b/doc/src/fpga_tools/packager/packager.md @@ -2,92 +2,99 @@ ## SYNOPSIS ## -`packager [options]` +`packager [arguments]` -## DESCRIPTION ## -The packager provides tools to help AFU developers create Accelerator Function files. The Accelerator Function file is the programming file for an AFU in the Intel® Acceleration Stack for FPGAs platform. It includes metadata the packager tool generates and a raw binary file (.rbf) that the Intel Quartus Prime software generates. +## Description ## +The packager provides tools that Accelerator Functional Unit (AFU) developers use to create Accelerator Function (AF) +files. The AF file is the programming file for an AFU on Intel® FPGA platforms. The packager tool concatenates +the metadata from the JSON file to a raw binary file `(.rbf)` that the Intel Quartus® Prime software generates. -Currently, the packager's only function is to create an AFU file. Refer to Section 2 for more information about the packager. The packager depends on a JSON file to describe AFU metadata. Refer to Section 3 for more information about the JASON file. +The packager's only function is to create an AF file. Refer to [Packager Command Syntax](#packager-command-syntax) for more information +about invoking the packager. The packager depends on a JSON file to describe AFU metadata. Refer to +[Accelerator Description File](#accelerator-description-file) for more information about the JSON file. -**The packager requires Python 2.7.1 and Python 2.7.3. The tool indicates if it is being called with a compatible version of Python.** +**The packager requires Python 2.7.1 and Python 2.7.3. The tool indicates if it is being called with a compatible +of Python.** -## PACKAGER INTERFACE ## +## Packager Command Syntax ## -The packager is a command line tool with the following interface: +The packager is a command line tool with the following syntax: -`$ packager [options]` +`$ packager [arguments]` -To display the list of commands for the packager, run: +The following table describes the `` arguments: -`$ packager help` +| Command | Arguments | Description | +|---------| ----------------| ------------| +| ```create-gbs``` | ```--rbf=```
```--afu=```
```--gbs=```
```--set-value=.```| Creates the AF file. The engineering name for this file is the green bit stream, abbreviated gbs. The `--rbf` and `--afu` arguments are required. `` is the path to the RBF file for the AFU. The Quartus® Prime software generates this RBF by compiling the AFU design. `` is the path to the Accelerator Description file. This is a JSON file that describes the metadata that `create-gbs` appends to the RBF. `` is the path to the RBF file for the FPGA Interface Manager (FIM) that contains the FPGA interface unit and other interfaces. If you do not specify the `--gbs`, the command defaults to `.gbs`. You can use the optional `--set-value=.` argument to set values for JSON metadata. To set more than one JSON value, list a series of `.` pairs.| +|```modify-gbs``` | ```--gbs=```| Modifies the AF file. The `--input-gbs`argument is required. If you do not provide the `--output-gbs` argument, `modify-gbs` overwrites the `--input-gbs` file. Use the `--set-value=.` argument to set values for JSON metadata. To set more than one JSON value, list a series of `.` pairs.| +|```gbs-info``` | ```--input-gbs=```| Prints information about the AF file. The `--input-gbs` argument is required.| +|```get-rbf``` | ```--gbs=```
```--rbf=```| Creates the the RBF by extracting it from the AF file. The `--gbs`argument is required. If you do not specify the `--rbf` agrument, the command defaults to `` | `--help` | Summarizes the `` options. Typing `packager --help` gives a list of `` values. Typing `packager --help` provides detailed help for `` | -To display help for a specific command, run: -`$ packager --help` +## Examples ## -To display the version of the packager tool, run: - -`$ packager version` - -To generate an AFU file, run: +To generate an AF file, run: `$ packager create-gbs --rbf= --afu= --gbs=` - is the path to the RBF file for the AFU. The Quartus Prime software generates this RBF by compiling the AFU. - is the path to the Accelerator Description file. This is a JSON file that describes the metadata that is appended to the AFU. - is the path to the RBF file for the FPGA interface manager (FIM) that contains the FPGA interface unit and other interfaces. - -**TIP**: JSON files can be very particular about things like trailing commas. If you’re getting errors, try using jsonlint.com to validate that your JSON is formatted correctly. +**TIP**: JSON files are very particular about syntax such as trailing commas. If you are getting errors, use `jsonlint.com` to +validate that your JSON is formatted correctly. -To modify metadata in an existing AFU file, run the following command: +To modify metadata in an existing AF, run the following command: `$ packager modify-gbs --input-gbs= --outputgbs= --set-value :` -You can pass in a number of : pairs with --set-value to update values in “afu- image”. +You can pass in a number of : pairs with --set-value to update values in an AF. -To print the metadata of an existing AFU: +To print the metadata of an existing AF: `$ packager get-info --gbs=` -To extract the RBF from the AFU: +To extract the RBF from the AF: `$ packager get-rbf --gbs= --rbf=` ## Accelerator Description File ## -This Accelerator Description File is a JSON file that describes an AFU. Its currently describes the metadata associated with a AFU. This metadata is used by the OPAE during reconfiguration. Here is an example file: +The Accelerator Description File is a JSON file that describes the metadata associated with an AFU. +The Open Progammable Accelerator Engine (OPAE) uses this metadata during reconfiguration. Here is an example file: ``` { - "version": 1 + "version": 1, "platform-name": "DCP", "afu-image": { "magic-no": 488605312, - "interface-uuid": "576c885b-0a4f-549b-ca2e-3b2e12d579f7", - "clock-frequency-low": "50", - "clock-frequency-high": "200", - "power" = 10, - "afc-clusters": [{ - "total-contexts": 1, - "name": "nlb_400", - "afc-type-uuid": "c000c966-0d82-4272-9aef-fe5f84570612" + "interface-uuid": "01234567-89AB-CDEF-0123-456789ABCDEF", + "power": 0, + "accelerator-clusters": [{ + "name": "dma_test_afu", + "total-contexts": 1, + "accelerator-type-uuid": "331DB30C-9885-41EA-9081-F88B8F655CAA" } ] } } ``` +The packager stores these parameter values in the resultant AF. After reprogramming the AFU using partial reconfiguration (PR), the +software driver reconfigures the PLLs by writing the clock-frequency-high and clock-frequency-low values (if present) over the +PCIe® and CCI interfaces. -The clock frequency fields are for OpenCL which requires PLL reconfiguration. Quartus Prime compilation derives a set of PLL parameter values to update the PLL Dynamic Reconfiguration Block. The metadata stores these parameter values. After reprogramming the AFU using partial reconfiguration (PR), the software driver reconfigures the PLL by writing these parameter values over PCIe/CCI. No kernel space floating point processing is necessary. - -**Note the version field. This file format may change as the architecture evolves. The version reflects changes to the file format.** +.. note:: +``` +The JSON file format may change as the architecture evolves. Any changes to the current format trigger an update +to the version number. +``` CATEGORY | NAME | TYPE | DESCRIPTION | MANDATORY ----------|------|------|-------------|---------- +---------|------|------|-------------|:----------:| Per-AFU | version | Integer | Version of the metadata format. | Yes Per-AFU | magic-no (to be deprecated)| Integer | Magic no. Associated with the FPGA Interface Manager. | No -Per-AFU | platform-name | String | Name of the platform for which the metadata is intended. The field value is “DCP” for Intel® Acceleration Stack for FPGAs. | No +Per-AFU | platform-name | String | Name of the platform for which the metadata is intended. The field value is “DCP” for Intel Acceleration Stack for FPGAs. | No Per-AFU | interface-uuid | UUID | Interface id associated with the FPGA Interface Manager. | Yes -Per-AFU | power | Integer | Accelerator Function power consumption, in watts. Set to 0 for Intel® Acceleration Stack for FPGAs platforms. | Yes +Per-AFU | power | Integer | Accelerator Function power consumption, in watts. Set to 0 for Intel Acceleration Stack for FPGAs platforms. | Yes Per-AFU | clock-frequency-low | Float | Clock frequency for 1st PLL (Clock network)1 in MHz. | No Per-AFU | clock-frequency-high | Float | Clock frequency for 2nd PLL (0 if absent) in MHz. | No Per-AFC Cluster | total-contexts | Integer | Number of AFCs in this cluster. Always be 1 in current architectures. | Yes diff --git a/doc/src/fpga_tools/userclk/userclk.md b/doc/src/fpga_tools/userclk/userclk.md index 21975cce28c5..56e7d5f537d4 100644 --- a/doc/src/fpga_tools/userclk/userclk.md +++ b/doc/src/fpga_tools/userclk/userclk.md @@ -17,19 +17,33 @@ userclk sets the frequency range for an AFU. ## OPTIONS ## -`-B,--bus` FPGA Bus number. +`-B,--bus` -`-D,--device` FPGA Device number. +FPGA Bus number. -`-F,--functio` FPGA function number. +`-D,--device` -`-S,--socket` FPGA socket number. +FPGA Device number. -`-P,--port` Port ID. +`-F,--functio` -`-H,--freq-high ` User clock high frequency. +FPGA function number. -`-L,--freq-low ` User clock low frequency. +`-S,--socket` + +FPGA socket number. + +`-P,--port` + +Port ID. + +`-H,--freq-high ` + +User clock high frequency. + +`-L,--freq-low ` + +User clock low frequency.