Updated Shell versioning details. (#520)

* Added new shell versioning FAQ * Updated shell versioning * Provided links to small shell
aws · Jun 3, 2021 · 4156888 · 4156888
1 parent 4323e78
commit 4156888
Show file tree

Hide file tree

Showing 9 changed files with 94 additions and 43 deletions.
diff --git a/ERRATA.md b/ERRATA.md
@@ -1,8 +1,8 @@
 
 # AWS EC2 FPGA HDK+SDK Errata
 
-## Shell v1.4 (04261818)
-[Shell\_04261818_Errata](./hdk/docs/AWS_Shell_ERRATA.md)
+## Shell Errata
+Shell errata is [documented here](./hdk/docs/AWS_Shell_ERRATA.md)
 
 ## HDK
 * Multiple SDE instances per CL is not supported in this release. Support is planned for a future release.
@@ -22,7 +22,7 @@ Q: Which designs does this bug affect?
 A: This bug only affects designs that instantiate the sh_ddr module.
 
 Q: How do I fix my design if I am affected by this bug?
-A: Pull aws-fpga release v1.4.19 or laterfrom the aws-fpga github and rebuild your cl design. 
+A: Pull aws-fpga release v1.4.19 or later from the aws-fpga github and rebuild your cl design. 
 The flop_ccf.sv files from the latest release that contain the fix are: [sh_ddr/synth/flop_ccf.sv](https://github.com/aws/aws-fpga/blob/master/hdk/common/shell_v04261818/design/sh_ddr/synth/flop_ccf.sv) & 
 [sh_ddr/sim/flop_ccf.sv](https://github.com/aws/aws-fpga/blob/master/hdk/common/shell_v04261818/design/sh_ddr/sim/flop_ccf.sv)
 

diff --git a/FAQs.md b/FAQs.md
@@ -449,26 +449,81 @@ Refer to [Virtual JTAG readme](./hdk/docs/Virtual_JTAG_XVC.md) for more details.
 
 <a name="shell"></a>
 ## General AWS FPGA Shell FAQs
+
+**Q: What is the AWS Shell?**
+An AWS Shell is in short the AWS platform logic implementing the FPGA external peripherals, PCIe, DRAM, and Interrupts in the FPGA.
+
+
 **Q: Do I need to interface to the AWS Shell?**
 
-Yes. The only way to interface to PCIe and the instance CPU is using the AWS Shell. The AWS Shell is included with every FPGA. There is no option to run the F1 FPGA without a Shell. The Shell takes care of the non-differentiating heavy lifting tasks like PCIe tuning, FPGA I/O assignment, power, thermal management, and runtime health monitoring.
+Yes. The only way to interface to PCIe and the instance CPU is using an AWS Shell. 
+An AWS Shell is included with every FPGA. There is no option to run the F1 FPGA without a Shell. 
+The Shell takes care of the non-differentiating heavy lifting tasks like PCIe tuning, FPGA I/O assignment, power, thermal management, and runtime health monitoring.
 
 
 **Q: Is a simulation model of the AWS Shell available?**
 
-Yes. The HDK includes a simulation model for the AWS shell. See the [HDK common tree](./hdk/common/verif) for more information on the Shell simulation model.
+Yes. The HDK includes a simulation model for the AWS shell. 
+See the [HDK common tree](./hdk/common/verif) for more information on the Shell simulation model.
 
 
 **Q: What resources within the FPGA does the AWS Shell consume?**
 
-The Shell consumes about 20% of the FPGA resources, and that includes the PCIe Gen3 X16, DMA engine, DRAM controller interface, ChipScope (Virtual JTAG) and other health monitoring and image loading logic. No modifications to the Shell or the partition pins between the Shell and the Custom Logic are possible by the FPGA developer.
+AWS provides multiple families of shells. 
+
+The F1 XDMA shell F1.X.1.4 shell consumes about 20% of the FPGA resources, and that includes the PCIe Gen3 X16, DMA engine, 
+DRAM controller interface, ChipScope (Virtual JTAG) and other health monitoring and image loading logic. 
+
+No modifications to the Shell or the partition pins between the Shell and the Custom Logic are possible by the FPGA developer.
+
+**Q: What different shells does AWS provide?**
+
+AWS Provides the following families of shells:
+
+| Shell Name| Shell Version | Dev Kit Branch | Description|
+|--------|--------|---------|-------|
+| F1 XDMA Shell | F1.X.1.4 | [master](https://github.com/aws/aws-fpga/) | Provides all the [interfaces listed here](https://github.com/aws/aws-fpga/blob/master/hdk/docs/AWS_Shell_Interface_Specification.md), includes DMA | 
+| F1 Small Shell | F1.S.1.0 | [small_shell](https://github.com/aws/aws-fpga/tree/small_shell) | Provides all the [interfaces listed here](https://github.com/aws/aws-fpga/blob/small_shell/hdk/docs/AWS_Shell_Interface_Specification.md). This shell does not include DMA engine and provides significant reduction in Shell resource usage. |
+
+**Q: How does AWS change Shell versions?**
+
+Shell version schema is defined below:
+```
+|Platform String| . |Short Shell name string| . |major| . | minor|
+
+Platform String
+    Changes with platform and also with FPGAs used within a platform.
+    
+    F1
+
+Short Shell name string
+    Short string to show the shell family
+    
+    S = Small shell
+    X = XDMA shell
+
+Major
+    Shell major version. 
+    This number increments when the RL interface changes
+    Increments are for RL interface breaking changes
+    
+Minor
+    Shell minor version.
+    This number increments when the RL implementation/interface sees minor changes
+    Increments are for feature additions, non breaking changes
+    
+```
+Examples of shell versions:
 
+F1 XDMA Shell - F1.X.1.3(Deprecated), F1.X.1.4
+Small Shell - F1.S.1.0
 
 <a name="troubleshooting"></a>
 ## Troubleshooting FAQs
 **Q: Why do I see error “vivado not found” while running hdk_setup.sh?**
 
-This is an indication that Xilinx Vivado tool set are not installed. Try installing the tool if you are working on your own environment, or alternative use AWS FPGA Development AMI available on AWS Marketplace, which comes with pre-installed Vivado toolset and license.
+This is an indication that Xilinx Vivado tool set are not installed. 
+Try installing the tool if you are working on your own environment, or alternative use AWS FPGA Development AMI available on AWS Marketplace, which comes with pre-installed Vivado toolset and license.
 
 
 **Q: Why did my example job run and die without generating a DCP file?**

diff --git a/README.md b/README.md
@@ -85,10 +85,12 @@ At the end of the development process, combining the Shell and CL creates an Ama
 
 The following table provides the shells currently available to develop your CL with. Each shell provides specific interfaces and features and currently needs to be used with the Dev Kit branch listed in the table.
 
-| Shell Version | Dev Kit Branch | Description|
-| --------|---------|-------|
-| v04261818 | [master](https://github.com/aws/aws-fpga/) | Provides all the [interfaces listed here](https://github.com/aws/aws-fpga/blob/master/hdk/docs/AWS_Shell_Interface_Specification.md) including DMA | 
-| v04182104 | [small_shell](https://github.com/aws/aws-fpga/tree/small_shell) | Provides all the [interfaces listed here](https://raw.githubusercontent.com/aws/aws-fpga/small_shell/hdk/docs/AWS_Shell_Interface_Specification.md). This shell does not include DMA engine and provides significant reduction in Shell resource usage. |
+| Shell Name| Shell Version | Dev Kit Branch | Description|
+|--------|--------|---------|-------|
+| F1 XDMA Shell | F1.X.1.4 | [master](https://github.com/aws/aws-fpga/) | Provides all the [interfaces listed here](https://github.com/aws/aws-fpga/blob/master/hdk/docs/AWS_Shell_Interface_Specification.md), includes DMA | 
+| F1 Small Shell | F1.S.1.0 | [small_shell](https://github.com/aws/aws-fpga/tree/small_shell) | Provides all the [interfaces listed here](https://github.com/aws/aws-fpga/blob/small_shell/hdk/docs/AWS_Shell_Interface_Specification.md). This shell does not include DMA engine and provides significant reduction in Shell resource usage. |
+
+For more details, check the [FAQ](./FAQs.md#general-aws-fpga-shell-faqs)
 
 ## Software-defined Development Environment
 

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,5 +1,13 @@
 # AWS EC2 FPGA HDK+SDK Release Notes
 
+## Release 1.4.19 (See [ERRATA](./ERRATA.md) for unsupported features)
+* Bug Fix release
+
+We have identified a bug in the `flop_ccf.sv` module that can potentially impact timing closure of designs.
+The module is instantiated in `sh_ddr.sv` and inadvertently introduces a timing path on the reset logic.
+Although there is no functional impact, it may increase Vivado tool’s effort in timing closure of design.
+There should be no functional impact from this bug if your design has already met timing.
+
 ## Release 1.4.18 (See [ERRATA](./ERRATA.md) for unsupported features)
 * FPGA developer kit now supports Xilinx Vivado/Vitis 2020.2
 

diff --git a/hdk/docs/AWS_Shell_ERRATA.md b/hdk/docs/AWS_Shell_ERRATA.md
@@ -1,6 +1,8 @@
-# AWS EC2 FPGA Shell Errata (04261818)
+# AWS EC2 FPGA Shell Errata 
 
-## Implementation Restrictions
+## AWS Shell F1.X.1.4 (04261818)
+
+### Implementation Restrictions
 * PCIE AXI4 interfaces between Custom Logic(CL) and Shell(SH) have following restrictions:
   * All PCIe transactions must adhere to the PCIe Express base spec
   * 4Kbyte Address boundary for all transactions(PCIe restriction)
@@ -16,12 +18,10 @@
 
 * AFI must be re-loaded after an instance re-boot.
 
-## Unsupported Features (Planned for future releases)
+### Unsupported Features
 * FPGA to FPGA over serial ring links for F1.16xl and F1.4xl
 * Aurora and Reliable Aurora modules for the FPGA-to-FPGA 
 * Cadence Xcelium simulations tools
 
-## Known Bugs/Issues
+### Known Bugs/Issues
 * **sh_cl_ddr_is_ready[2:0]** outputs of sh_ddr.sv are not synchronized to clk_main_a0.  Developers should synchronize these signals to clk_main_a0.
-
-
diff --git a/hdk/docs/AWS_Shell_Interface_Specification.md b/hdk/docs/AWS_Shell_Interface_Specification.md
@@ -1,18 +1,4 @@
 # AWS Shell Interface Specification
-
-## Revision History
-
-2016/11/28   -   Initial public release with HDK release version
-
-2016/12/06   -   Added capability to remove DDR controllers in the CL through parameters in `sh_ddr.sv`
-
-2017/02/02   -   Major updates for Feb/2017 Shell, that includes interrupts, wider and more buses,  DMA, Virtual LED and other. (Please refer to [Release Notes](../../RELEASE_NOTES.md) for details)
-
-2017/07/29   -   Updates for Jul/2017 Shell
-
-2017/11/16   -   Updates for v1.3.4
-
-2018/05/10   -   Updates for 1.4
 
 # Table of Contents:
 
@@ -89,7 +75,7 @@ This document specifies the hardware interface and functional behavior between t
 This specification applies to  Xilinx Virtex Ultrascale Plus platform available on EC2 F1, each update of the Shell 
  is tagged with a revision number. Note while AWS tries to keep the revision constant, sometimes it is necessary to update the revision due to discovered issues or added functionality. The HDK release includes the latest Shell version under `/hdk/common/shell_latest`
 
-Starting from 1.4, The shell is reconfigurable, allowing, in most cases, developers to select which shell version to create the AFI with.  Going forward, new shell versions will NOT require updated CL implementation and regenerating the AFI (still a requirement with 1.4 shell.)
+Starting from F1.X.1.4, The shell is reconfigurable, allowing, in most cases, developers to select which shell version to create the AFI with.  Going forward, new shell versions will NOT require updated CL implementation and regenerating the AFI (still a requirement with F1.X.1.4 shell.)
 
 
 <a name="conventions"></a>
@@ -224,7 +210,7 @@ These parameters are used to control which DDR controllers are impemented in the
 
 ### DRAM Content Preservation between AFI Loads
 
-Shell version 1.4 allows the DDR state to be preserved when dynamically changing CL logic. Any AFI generated with a v1.4 shell will enable DRAM content preservation by default.
+Shell version F1.X.1.4 allows the DDR state to be preserved when dynamically changing CL logic. Any AFI generated with a v1.4 shell will enable DRAM content preservation by default.
 Please refer to the [guide on how to use the DRAM data retention mode to preserve the content of DRAM across AFI loads](./data_retention.md) for more details on utilizing this feature.
 
 <a name="dma"></a>

diff --git a/hdk/docs/AWS_Shell_RELEASE_NOTES.md b/hdk/docs/AWS_Shell_RELEASE_NOTES.md
@@ -1,6 +1,6 @@
 # AWS Shell Release Notes
 
-# v04261818
+# F1 XDMA Shell - F1.X.1.4(v04261818)
 * Fixed AXI-L Interface Ordering.  Read requests on the AXI-L interfaces (BAR1, OCL, SDA) will not pass previous write requests.
 * Increased XDMA PCIS interface timeout to 5 seconds
 * Clock group A supports synchronous clocks within the group (default is clocks are synchronous)

diff --git a/hdk/docs/AWS_Shell_V1.4_Migration_Guidelines.md b/hdk/docs/AWS_Shell_V1.4_Migration_Guidelines.md
@@ -1,15 +1,15 @@
-# Shell v1.4 Migration Document
+# Shell F1.X.1.4 Migration Document
 
 
-This document describes the changes required when migrating your design from shell v1.3 to shell v1.4.
+This document describes the changes required when migrating your design from shell F1.X.1.3 to shell F1.X.1.4.
 The HDK build scripts have changed to reflect the new v1.4 shell’s floorplan and newer Vivado tools. It’s strongly recommended users move to these scripts. Users who have already customized v1.3 scripts should diff those with the v1.4 scripts and be sure to include all new parameters that have been added to v1.4 scripts.
 
 1. Upgrade Vivado Tools to version 2019.1 or later. Needs [FPGA DEVELOPER AMI 1.4 or later](../../README.md#fpga-developer-ami)
 
 2. The hierarchy for CL & SH modules have changed. Now they are instantiated in  "WRAPPER_INST" Module.
      The paths in your Build scripts, constraints &  verification components have to be updated.
 
- | v1.3 Shell | v1.4 Shell |
+ | F1.X.1.3 Shell | F1.X.1.4 Shell |
  |------------|------------|
  | CL/blkA/sublockB/componentC/celld/signalX | WRAPPER_INST/CL/blkA/sublockB/componentC/celld/signalX |
  | SH/blkA/sublockB/componentC/celld/signalX | WRAPPER_INST/SH/blkA/sublockB/componentC/celld/signalX |
@@ -34,13 +34,13 @@ NOTE: Only INCR burst mode is supported on AXI-4 buses between CL/Shell interfac
 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.
 
-8. Please use below information to update CL pblock constraints to optimize your design in Shel v1.4.
-      - Shell V1.4 is slightly larger than Shell v1.3. CL floorplan may need to be tweaked to account for the larger Shell V1.4.
+8. Please use below information to update CL pblock constraints to optimize your design in Shell F1.X.1.4.
+      - Shell F1.X.1.4 is slightly larger than Shell F1.X.1.3. CL floorplan may need to be tweaked to account for the larger shell.
         Please review pblock constriants of CL for conflicting regions.
-      - Following are the interface placement changes between Shell v1.3 & v1.4
+      - Following are the interface placement changes between Shell F1.X.1.3 & F1.X.1.4
 
 
-      | INTERFACE | Shell v1.3 SLR | SHELL v1.4 SLR |
+      | INTERFACE | Shell F1.X.1.3 SLR | SHELL F1.X.1.4 SLR |
       |-----------|---------------|---------------|
       | CL_SH_DDR |MID/BOTTOM SLR  | MID SLR |
       | BAR1 | MID SLR  | MID SLR |

diff --git a/hdk/docs/data_retention.md b/hdk/docs/data_retention.md
@@ -6,8 +6,8 @@ Workloads that require multiple AFIs to process a data set can take advantage of
 
 For an AFI to support data retention, the following requirements must be met:
 
-1. The AFI must be built with shell version 1.4 or higher.
-2. The AFI must be built with the version of `sh_ddr.sv` shipped with 1.4 or higher.
+1. The AFI must be built with shell version F1.X.1.4 or higher.
+2. The AFI must be built with the version of `sh_ddr.sv` shipped with Dev Kit 1.4.0 or higher.
 3. The AFI must use all four DDR controllers. (All of `DDR_A_PRESENT`, `DDR_B_PRESENT`, `DDR_D_PRESENT` must be set. DDRC is part of the shell and is always present.)
 
 To use data retention across AFI loads, the following conditions must be met: