Doc updates and test fixes (#538)

* Update DCV.md (#697) * Update and fix test failures (#698) * Fixed the non root test * Fixed documentation link failures by adding an updated ssl context * Update afi power doc (#699) * specify afi-power warning/violation triggers * Describe when afi-power-warning and afi-power-violation conditions trigger. * fix indentation of sh_cl_pwr_state Co-authored-by: kyyalama2 <[email protected]> Co-authored-by: AWScsaralay <[email protected]>
aws · Oct 4, 2021 · ea4baee · ea4baee
1 parent 7369ab1
commit ea4baee
Show file tree

Hide file tree

Showing 10 changed files with 98 additions and 82 deletions.
diff --git a/ERRATA.md b/ERRATA.md
@@ -9,7 +9,7 @@ Shell errata is [documented here](./hdk/docs/AWS_Shell_ERRATA.md)
 * DRAM Data retention is not supported for CL designs with less than 4 DDRs enabled
 * Combinatorial loops in CL designs are not supported.
   * We will display a `UNKNOWN_BITSTREAM_GENERATE_ERROR` on detection of a combinatorial loop in the CL design and an AFI will not be generated.
-* Connecting one of the clocks provided from the shell (clk_main_a0, clk_extra_a1, etc...) directly to a BUFG in the CL is not supported by the Xilinx tools and may result in a non-functional clock. To workaround this limitation, it is recommended to use an MMCM to feed the BUFG (clk_from_shell -> MMCM -> BUFG). Please refer to [Xilinx AR# 73360](https://www.xilinx.com/support/answers/73360.html) for further details.
+* Connecting one of the clocks provided from the shell (clk_main_a0, clk_extra_a1, etc...) directly to a BUFG in the CL is not supported by the Xilinx tools and may result in a non-functional clock. To workaround this limitation, it is recommended to use an MMCM to feed the BUFG (clk_from_shell -> MMCM -> BUFG). Please refer to [Xilinx AR# 73360](https://support.xilinx.com/s/article/73360?language=en_US) for further details.
 
 ### flop_ccf.sv bug
 
@@ -35,7 +35,7 @@ AWS customers may experience hardware failures including: post calibration data
 To detect if your build is impacted by this bug, AWS recommends all EC2 F1 customers utilizing the DDR4 IP in their designs should run a TCL script on the design checkpoint point (DCP) to check to determine if the design is susceptible to this issue. If the check passes, your design is safe to use as the hardware will function properly. 
 If the check fails, the design is susceptible to the issue and will need to be regenerated using the same tool version with the AR 73068 patch. 
 For designs under development, we recommend applying the patch to your on-premises tools or update to developer kit v1.4.15. 
-For additional details, please refer to the [Xilinx Answer Record #73068](https://www.xilinx.com/support/answers/73068.html)
+For additional details, please refer to the [Xilinx Answer Record #73068](https://support.xilinx.com/s/article/73068?language=en_US)
 
 We recommend using [Developer Kit Release v1.4.15a](https://github.com/aws/aws-fpga/releases/tag/v1.4.15a) or newer to allow for patching and fixing the DDR4 IP timing exception by re-generating the IP.
 
@@ -45,8 +45,8 @@ We recommend using [Developer Kit Release v1.4.15a](https://github.com/aws/aws-f
 
 | Library(verilog) | Simulator | Xilinx Answer Record | 
 |---|---|---|
-| `sync_ip` | Cadence IES | [AR72795](https://www.xilinx.com/support/answers/72795.html) |
-| `hdmi_gt_controller_v1_0_0` | Synopsys VCS | [AR72601](https://www.xilinx.com/support/answers/72601.html) |
+| `sync_ip` | Cadence IES | [AR72795](https://support.xilinx.com/s/article/72795?language=en_US) |
+| `hdmi_gt_controller_v1_0_0` | Synopsys VCS | [AR72601](https://support.xilinx.com/s/article/72601?language=en_US) |
 
 ## SDK
 

diff --git a/developer_resources/DCV.md b/developer_resources/DCV.md
@@ -61,10 +61,10 @@ If you experience issues please refer to the [Official DCV documentation](https:
 
    ```
    sudo rpm --import https://d1uj6qtbmh3dt5.cloudfront.net/NICE-GPG-KEY
-   wget https://d1uj6qtbmh3dt5.cloudfront.net/2021.1/Servers/nice-dcv-2021.1-10598-el7-x86_64.tgz
-   tar -xvzf nice-dcv-2021.1-10598-el7-x86_64.tgz && cd nice-dcv-2021.1-10598-el7-x86_64
-   sudo yum install nice-dcv-server-2021.1.10598-1.el7.x86_64.rpm
-   sudo yum install nice-xdcv-2021.1.392-1.el7.x86_64.rpm
+   wget https://d1uj6qtbmh3dt5.cloudfront.net/2021.2/Servers/nice-dcv-2021.2-11048-el7-x86_64.tgz
+   tar -xvzf nice-dcv-2021.2-11048-el7-x86_64.tgz && cd nice-dcv-2021.2-11048-el7-x86_64
+   sudo yum install nice-dcv-server-2021.2.11048-1.el7.x86_64.rpm
+   sudo yum install nice-xdcv-2021.2.406-1.el7.x86_64.rpm
 
    sudo systemctl enable dcvserver
    sudo systemctl start dcvserver
@@ -100,7 +100,7 @@ If you experience issues please refer to the [Official DCV documentation](https:
    **NOTE: You will have to create a new session if you restart your instance.** 
 
    ```
-   dcv create-session --type virtual --user centos centos
+   dcv create-session --type virtual --user centos centos --owner centos
    ```
 
 1. Connect to the DCV Remote Desktop session
@@ -125,4 +125,4 @@ If you experience issues please refer to the [Official DCV documentation](https:
 
 1. Logging in should show you your new GUI Desktop:
 
-    ![DCV Desktop](images/dcv_desktop.png)
+    ![DCV Desktop](images/dcv_desktop.png)
diff --git a/docs/examples/example_list.md b/docs/examples/example_list.md
@@ -10,7 +10,6 @@
 | High Level Synthesis | [Digital Up-Converter - cl\_hls\_dds\_hlx](../../hdk/cl/examples/cl_hls_dds_hlx) | HLx - C-to-RTL  | Demonstrates an example application written in C that is synthesized to RTL (Verilog) |
 | Custom Hardware with Software Defined Acceleration | [RTL Kernels](https://github.com/Xilinx/Vitis_Accel_Examples/tree/master/rtl_kernels) | Vitis - RTL (Verilog) + C/C++/OpenCL  | These examples demonstrate developing new hardware designs (RTL) in a Software Defined workflow|
 | Vitis Compression Libraries | [File Compression using GZip](https://github.com/Xilinx/Vitis_Accel_Examples/tree/master/library_examples/gzip_app) | Vitis - C/C++/OpenCL  | This example demonstrates how to use Vitis Libraries to speed up GZIP compression on an FPGA |
-| Vitis BLAS libraries | [Matrix Transposer using BLAS](https://github.com/Xilinx/Vitis_Accel_Examples/tree/master/library_examples/transp) | Vitis - C/C++/OpenCL  | This example shows how to use Vitis BLAS Libraries to create a Matrix Transposer on an FPGA |
 | Vitis Financial libraries | [Monte Carlo European Engine](https://github.com/Xilinx/Vitis_Accel_Examples/tree/master/library_examples/MCEuropeanEngine) | Vitis - C/C++/OpenCL  | This example shows how to use Vitis Financial Libraries to accelerate MCEuropean Engine on an FPGA|
 
 ## Application Notes 

diff --git a/hdk/docs/AWS_Shell_V1.4_Migration_Guidelines.md b/hdk/docs/AWS_Shell_V1.4_Migration_Guidelines.md
@@ -29,7 +29,7 @@ NOTE: Only INCR burst mode is supported on AXI-4 buses between CL/Shell interfac
 
 5. Upgrade to latest for [SH_DDR IP](../common/shell_v04261818/design/sh_ddr) .
 
-6. All Xilinx IP  in your CL must to be upgraded to 2017.4 or later version. see [vivado 2017.4 release notes for recommended version](https://www.xilinx.com/support/answers/70386.html)
+6. All Xilinx IP  in your CL must to be upgraded to 2017.4 or later version. see [vivado 2017.4 release notes for recommended version](https://support.xilinx.com/s/article/70386?language=en_US)
 
 7. [ILA cores](../common/shell_v04261818/design/ip/cl_debug_bridge) need to be upgraded for 2017.4 or later
      Please refer to the [cl_dram_dma](../cl/examples/cl_dram_dma/design) example for ILA hookup on PCIS interface.

diff --git a/hdk/docs/Programmer_View.md b/hdk/docs/Programmer_View.md
@@ -12,7 +12,7 @@ There are two parts required to work with AWS FPGA: Management and Runtime, and
 
   **\[B\]** As a C-library called [FPGA Management Lib](../../sdk/userspace/fpga_libs/fpga_mgmt/) to be compiled with the developer's C/C++ application.
 
-  **\[C\]** Pre-integrated with [OpenCL runtime library](../../SDAccel)
+  **\[C\]** Pre-integrated with [OpenCL runtime library](../../Vitis)
 
 2. **Runtime code**: is required for reading/writing from/to the Custom Logic, handling interrupts, and using the DMA. This is provided by:
 
@@ -22,6 +22,6 @@ There are two parts required to work with AWS FPGA: Management and Runtime, and
 
   **\[F\]** A [Userspace Interrupt/Event notification](../../sdk/linux_kernel_drivers/xdma/user_defined_interrupts_README.md) using standard POSIX API like open() and poll(), to be used in any C/C++ application. This Interrupt/Event interface requires installing the [XDMA kernel driver](../../sdk/linux_kernel_drivers/xdma/xdma_install.md) - marked as item **\[G\]**.
 
-  **\[I\]** An [openCL ICD](https://wikipedia.org/wiki/OpenCL#Implementations) library that links with openCL runtime application, like the one generated by Xilinx' SDAccel. 
+  **\[I\]** An openCL ICD library that links with openCL runtime application, like the one generated by Xilinx Vitis. 
 
 
diff --git a/hdk/docs/afi_power.md b/hdk/docs/afi_power.md
@@ -4,7 +4,12 @@ There are 2 power related scenarios that need to be avoided:
 1. Ramping too quickly between low power and high power states
 
 ## Exceeding Maximum FPGA power
-The Xilinx UltraScale+ FPGA devices used on the F1 instances have a maximum power limit that must be maintained.  If a loaded AFI consumes maximum power, the F1 instance will automatically gate the input clocks provided to the AFI in order to prevent errors within the FPGA. This is called an afi-power-violation. Specifically, when power (Vccint) is greater than 85 watts, the CL will have a power warning bit set. Above that level, the CL is in danger of being clock gated due to an afi-power-violation.
+The Xilinx UltraScale+ FPGA devices used on the F1 instances impose a Maximum Power Consumption Limit of 85 Watts. The F1 Instance takes following actions if the AFI causes power consumption to exceed the imposed limit:
+1. The ```afi-power-warning``` is triggered when the AFI running on an F1 instance exceeds the power consumption limit of 85W. The clocks from Shell to the CL are not gated while this warning is set. This is an indication that Customer Logic should reduce power consumption.
+2. If the high power consumption is not mitigated then the Shell asserts ```afi-power-violation``` and gate the clocks to the CL. 
+3. In addition, if the F1 Instance detects high power consumption at the time of AFI load then ```afi-power-violation``` is set, clocks are disabled and any transactions along Shell-CL interface results in timeout.
+
+For all practical purposes, we strongly recommend customer design to act on ```afi-power-warning``` to reduce power consumption.
 
 ## Ramping too Quickly Between Low Power and High Power States
 Even though your design may have a max power which is lower than the previously described limit, you might see issues if you rapidly switch between low power and high power states. A common scenario is upon startup the design goes from a low power reset state to the max power state instantly. In failing cases the host will appear to lose contact with the FPGA card and can only recover with an instance stop/restart. To prevent this from happening care must be taken to sequence the design such that it slowly increases the power requirements to max power instead of instantaneously doing so. 
@@ -27,24 +32,24 @@ Power consumption (Vccint):
 Power consumption may drift slightly over time, and may vary from instance to instance. In order to prevent a power violation, it's important to take into account this natural variation, and design with margin accordingly.
 
 ## Lowering Power Based on High Power Events Reported by the Shell
-In order to help developers avoid these overpower events, the F1 system indicates a afi-power-warning on the CL interface (sh_cl_pwr_state[1:0]) when the FPGA power levels are above 85 watts, and the CL is in danger of having it's clocks disabled. This should allow the CL to self-throttle, or reduce power-hungry optimizations, and avoid having its input clocks disabled.
+In order to help developers avoid these overpower events, the F1 system indicates a ```afi-power-warning``` on the CL interface (```sh_cl_pwr_state[1:0]```) when the FPGA power levels are above 85 watts, and the CL is in danger of having it's clocks disabled. This should allow the CL to self-throttle, or reduce power-hungry optimizations, and avoid having its input clocks disabled.
 
-Power state of the FPGA:  sh_cl_pwr_state[1:0]
-0x0 – OK
-0x1 – UNUSED
-0x2 – afi-power-warning
-0x3 – afi-power-violation
+Power state of the FPGA:  ```sh_cl_pwr_state[1:0]```:
+* 0x0 – OK
+* 0x1 – UNUSED
+* 0x2 – ```afi-power-warning```: Set when AFI exceeds the Power Consumption limit of 85W. Shell-CL clocks are not gated. 
+* 0x3 – ```afi-power-violation```: Set when AFI continues to exceed Power Consumption limit and Shell-CL clocks are shut off. 
 
 ## Detecting power-violation
-The fpga-describe-local-image command will show that the AFI load has failed due to an afi-power-violation
+The fpga-describe-local-image command will show that the AFI load has failed due to an ```afi-power-violation```
 
 ```
     # fpga-describe-local-image -S 0
     AFI          0       none                    load-failed          7        afi-power-violation        17       0x071417d3
     AFIDEVICE    0       0x1d0f      0xf000      0000:00:1d.0
 ```
 
-An afi-power-violation can occur either when the FPGA is first loaded, or while the FPGA is running a particularly power-intense workload. If the afi-power-violation occurs during a fpga-load-local-image, the load local image will itself fail with the afi-power-violation error.  After a afi-power-violation, transactions to CL will trigger [timeouts on all Shell to CL interfaces](./HOWTO_detect_shell_timeout.md). 
+An ```afi-power-violation``` can occur either when the FPGA is first loaded, or while the FPGA is running a particularly power-intense workload. If the ```afi-power-violation``` occurs during a fpga-load-local-image, the load local image will itself fail with the ```afi-power-violation``` error.  After a ```afi-power-violation```, transactions to CL will trigger [timeouts on all Shell to CL interfaces](./HOWTO_detect_shell_timeout.md). 
 
 ## Analyze power reports from Vivado
 Once the AFI power has been identified on F1, we recommend using Vivado to analyze the design to help reduce power.  First, open the DCP (Design check point) in the Vivado GUI.  Then, run the tcl command within Vivado:
@@ -70,7 +75,7 @@ https://www.xilinx.com/support/documentation/sw_manuals/xilinx2017_2/ug907-vivad
 Using a lower clock frequency from the [supported clock recipe](./clock_recipes.csv) will reduce the power consumed by the AFI.  
 
 ## Recovering from clock gating
-When an afi-power-violation occurs, the FPGA can still be loaded and cleared, but the clocks cannot be re-enabled without reloading the FPGA. Any AFI load or clear will restore full functionality to the FPGA.
+When an ```afi-power-violation``` occurs, the FPGA can still be loaded and cleared, but the clocks cannot be re-enabled without reloading the FPGA. Any AFI load or clear will restore full functionality to the FPGA.
 
 # Power Savings Techniques
 Here are some low power design techniques that can be used to lower the overall power or minimize instantaneous power ramps.
@@ -90,6 +95,3 @@ Power is consumed whenever a node in the design switches high or low. Reducing t
 **Architectural Power Savings**: A global power savings technique is to control power at the top-level Architectural Level. There is typically a block diagram of the overall design. By gating the clocks to top-level blocks and/or creating enables for the sequential elements in the design, these blocks can be put into low power modes when they aren't being used. It's critical to only enable the blocks that are required for the job.
 
 **Reducing Instantaneous Swings in Power**: Care must be taken to ensure there aren't large swings between low power and high power states. Sequencing the enables to the top-level architectural blocks will allow the design to slowly ramp to max power levels.
-
-
-
diff --git a/sdk/apps/virtual-ethernet/README.md b/sdk/apps/virtual-ethernet/README.md
@@ -9,7 +9,7 @@ The Virtual Ethernet framework facilitates streaming Ethernet frames from a netw
 In order to get the most from this document, readers may want to familiarize themselves with the following:
 
 1. The [F1 customer logic flow](../../../hdk/README.md#endtoend); creating and loading AFIs (Amazon FPGA Images)
-2. [DPDK](http://dpdk.org) (Data Plane Development Kit), a framework for creating high performance network traffic handling tools in userspace by limiting context switches, locks, or other blocking logic.
+2. [DPDK](https://dpdk.org) (Data Plane Development Kit), a framework for creating high performance network traffic handling tools in userspace by limiting context switches, locks, or other blocking logic.
 3. [EC2 Networking Concepts](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_Network_and_Security.html)
 
 # Virtual Ethernet Architecture