diff --git a/deploy/sample-backup-configs/sample_config_hwdb.yaml b/deploy/sample-backup-configs/sample_config_hwdb.yaml index 969126ba..ec3450db 100644 --- a/deploy/sample-backup-configs/sample_config_hwdb.yaml +++ b/deploy/sample-backup-configs/sample_config_hwdb.yaml @@ -63,7 +63,6 @@ vitis_firesim_gemmini_rocket_singlecore_no_nic: bitstream_tar: https://raw.githubusercontent.com/firesim/firesim-public-bitstreams/0af81b912264abbe3f90f8140987814291090560/vitis/vitis_firesim_gemmini_rocket_singlecore_no_nic.tar.gz deploy_quintuplet_override: null custom_runtime_config: null -# DOCREF START: Xilinx Alveo U250 HWDB Entries alveo_u250_firesim_rocket_singlecore_no_nic: bitstream_tar: https://raw.githubusercontent.com/firesim/firesim-public-bitstreams/1dc6be48bfe043bbc47e24660c1ef5076a22b7e4/xilinx_alveo_u250/alveo_u250_firesim_rocket_singlecore_no_nic.tar.gz deploy_quintuplet_override: null @@ -72,7 +71,6 @@ alveo_u250_firesim_gemmini_rocket_singlecore_no_nic: bitstream_tar: https://raw.githubusercontent.com/firesim/firesim-public-bitstreams/9de6c6cd854ff613114b04a2c67d7558e55d456c/xilinx_alveo_u250/alveo_u250_firesim_gemmini_rocket_singlecore_no_nic.tar.gz deploy_quintuplet_override: null custom_runtime_config: null -# DOCREF END: Xilinx Alveo U250 HWDB Entries alveo_u200_firesim_rocket_singlecore_no_nic: bitstream_tar: https://raw.githubusercontent.com/firesim/firesim-public-bitstreams/0abb07d46eced6b54e07026533f85bdc73f5a15e/xilinx_alveo_u200/alveo_u200_firesim_rocket_singlecore_no_nic.tar.gz deploy_quintuplet_override: null @@ -88,4 +86,4 @@ xilinx_vcu118_firesim_rocket_singlecore_4GB_no_nic: nitefury_firesim_rocket_singlecore_no_nic: bitstream_tar: https://raw.githubusercontent.com/firesim/firesim-public-bitstreams/b06e34569c2e4b350f8adeb96168244f2d43422b/rhsresearch_nitefury_ii/nitefury_firesim_rocket_singlecore_no_nic.tar.gz deploy_quintuplet_override: null - custom_runtime_config: null \ No newline at end of file + custom_runtime_config: null diff --git a/docs/Advanced-Usage/Manager/Manager-Configuration-Files.rst b/docs/Advanced-Usage/Manager/Manager-Configuration-Files.rst index 7a366712..aa14474b 100644 --- a/docs/Advanced-Usage/Manager/Manager-Configuration-Files.rst +++ b/docs/Advanced-Usage/Manager/Manager-Configuration-Files.rst @@ -159,7 +159,7 @@ are homogeneous and use this value for all nodes. You should set this to one of the hardware configurations you have defined already in ``config_hwdb.yaml``. You should set this to the NAME (mapping title) of the -hardware configuration from ``config_hwdb.yaml``, NOT the actual AGFI or ``xclbin`` itself +hardware configuration from ``config_hwdb.yaml``, NOT the actual AGFI or ``bitstream_tar`` itself (NOT something like ``agfi-XYZ...``). @@ -316,7 +316,7 @@ write: ``agfis_to_share`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. Warning:: This is only used in the AWS EC2 case. +.. Note:: This is only used in the AWS EC2 case. This is used by the ``shareagfi`` command to share the specified agfis with the users specified in the next (``share_with_accounts``) section. In this section, @@ -342,7 +342,7 @@ you would use: ``share_with_accounts`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. Warning:: This is only used in the AWS EC2 case. +.. Note:: This is only used in the AWS EC2 case. A list of AWS account IDs that you want to share the AGFIs listed in ``agfis_to_share`` with when calling the manager's ``shareagfi`` command. You @@ -470,7 +470,7 @@ to the relative name of the config. For example, ``bit_builder_recipe`` """"""""""""""""""""""" -This specifies the bitstream type to generate for a particular recipe (ex. build a Vitis ``xclbin``). +This specifies the bitstream type to generate for a particular recipe. This must point to a file in ``deploy/bit-builder-recipes/``. See :ref:`bit-builder-recipe` for more details on bit builders and their arguments. @@ -497,12 +497,12 @@ Here is a sample of this configuration file: This file tracks hardware configurations that you can deploy as simulated nodes in FireSim. Each such configuration contains a name for easy reference in higher-level -configurations, defined in the section header, an handle to a bitstream (i.e. an AGFI or ``xclbin`` path), which represents the +configurations, defined in the section header, an handle to a bitstream (i.e. an AGFI or ``bitstream_tar`` path), which represents the FPGA image, a custom runtime config, if one is needed, and a deploy quintuplet override if one is necessary. -When you build a new bitstream, you should put the default version of it in this -file so that it can be referenced from your other configuration files (i.e. the AGFI ID or ``xclbin`` path). +When you build a new bitstream, you should put it in this +file so that it can be referenced from your other configuration files. The following is an example section from this file - you can add as many of these as necessary: @@ -512,10 +512,12 @@ these as necessary: :start-after: DOCREF START: Example HWDB Entry :end-before: DOCREF END: Example HWDB Entry -``NAME_GOES_HERE`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Here are the components of these entries: -In this example, ``firesim_rocket_quadcore_nic_l2_llc4mb_ddr3`` is the name that will be +The name: ``firesim_boom_singlecore_nic_l2_llc4mb_ddr3`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this example, ``firesim_boom_singlecore_nic_l2_llc4mb_ddr3`` is the name that will be used to reference this hardware design in other configuration locations. The following items describe this hardware configuration: @@ -523,22 +525,18 @@ items describe this hardware configuration: """"""""""""""" This represents the AGFI (FPGA Image) used by this hardware configuration. -Only used in AWS EC2 F1 FireSim configurations (a ``xclbin`` key/value cannot exist with this +Only used in AWS EC2 F1 FireSim configurations (a ``bitstream_tar`` key/value cannot exist with this key/value in the same recipe). -``xclbin`` -""""""""""""""" - -Indicates where the bitstream (FPGA Image) is located, may be one of: - * A Uniform Resource Identifier (URI), (see :ref:`uri-path-support` for details) - * A filesystem path available to the manager. Local paths are relative to the `deploy` folder. - ``bitstream_tar`` """"""""""""""""" +This is not shown in the example entry above, but would be used for an on-premises bitstream. + Indicates where the bitstream (FPGA Image) and metadata associated with it is located, may be one of: - * A Uniform Resource Identifier (URI), (see :ref:`uri-path-support` for details) - * A filesystem path available to the manager. Local paths are relative to the `deploy` folder. + +* A Uniform Resource Identifier (URI), (see :ref:`uri-path-support` for details) +* A filesystem path available to the manager. Local paths are relative to the `deploy` folder. ``deploy_quintuplet_override`` """""""""""""""""""""""""""""" @@ -567,11 +565,13 @@ to the relative name of the config. For example, ``driver_tar`` """"""""""""""""""""""""""""" -They key can be one of: - * A Uniform Resource Identifier (URI), (see :ref:`uri-path-support` for details) - * A filesystem path available to the manager. Local paths are relative to the `deploy` folder. -When this key is present, the local driver will not build from source. +The value for this key can be one of: + +* A Uniform Resource Identifier (URI), (see :ref:`uri-path-support` for details) +* A filesystem path available to the manager. Local paths are relative to the `deploy` folder. + +When this key is present, the FireSim FPGA-driver software will not be built from source. Instead, during `firesim infrasetup`, this file will be deployed and extracted into the `sim_slot_X` folder on the run farm instance. This file may be a `.tar`, `.tar.gz`, `.tar.bz2` or any other format that GNU tar (version 1.26) @@ -586,7 +586,7 @@ Add more hardware config sections, like ``NAME_GOES_HERE_2`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can add as many of these entries to ``config_hwdb.yaml`` as you want, following the format -discussed above (i.e. you provide ``agfi`` or ``xclbin``, ``deploy_quintuplet_override``, and ``custom_runtime_config``). +discussed above (i.e. you provide ``agfi`` or ``bitstream_tar``, ``deploy_quintuplet_override``, and ``custom_runtime_config``). .. _run-farm-recipe: @@ -605,7 +605,7 @@ This key/value specifies a run farm class to use for launching, managing, and te run farm hosts used for simulations. By default, run farm classes can be found in :gh-file-ref:`deploy/runtools/run_farm.py`. However, you can specify your own custom run farm classes by adding your python file to the ``PYTHONPATH``. -For example, to use the ``AWSEC2F1`` build farm class, you would write ``run_farm_type: AWSEC2F1``. +For example, to use the ``AWSEC2F1`` run farm class, you would write ``run_farm_type: AWSEC2F1``. ``args`` ^^^^^^^^^^^^^^^^^^^^^ @@ -617,12 +617,8 @@ the ``_parse_args`` function in the run farm class given by ``run_farm_type``. ``aws_ec2.yaml`` run farm recipe ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This run farm recipe configures a FireSim run farm to use AWS EC2 instances. - -Here is an example of this configuration file: - -.. literalinclude:: /../deploy/run-farm-recipes/aws_ec2.yaml - :language: yaml +The run farm recipe shown above configures a FireSim run farm to use AWS EC2 instances. +It contains several key/value pairs: ``run_farm_tag`` """""""""""""""" @@ -734,7 +730,7 @@ for AWS EC2 simulations. ``externally_provisioned.yaml`` run farm recipe ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This run farm is an allows users to provide an list of pre-setup unmanaged run farm hosts (by hostname or IP address) that +This run farm allows users to provide a list of pre-setup unmanaged run farm hosts (by hostname or IP address) that they can run simulations on. Note that this run farm type does not launch or terminate the run farm hosts. This functionality should be handled by the user. For example, users can use this run farm type to run simulations locally. @@ -752,7 +748,7 @@ simulations across all run farm hosts. For example, this class manages how to flash FPGAs with bitstreams, how to copy back results, and how to check if a simulation is running. By default, deploy platform classes can be found in :gh-file-ref:`deploy/runtools/run_farm_deploy_managers.py`. However, you can specify your own custom run farm classes by adding your python file to the ``PYTHONPATH``. -There are default deploy managers / platforms that correspond to AWS EC2 F1 FPGAs, Vitis FPGAs, and Xilinx Alveo U250/U280 FPGAs, ``EC2InstanceDeployManager``, ``VitisInstanceDeployManager``, ``XilinxAlveo{U250,U280}InstanceDeployManager``, respectively. +There are default deploy managers / platforms that correspond to AWS EC2 F1 FPGAs, Vitis FPGAs, Xilinx Alveo U250/U280 FPGAs, Xilinx VCU118 FPGAs, and RHS Research Nitefury II FPGAs: ``EC2InstanceDeployManager``, ``VitisInstanceDeployManager``, ``Xilinx{AlveoU250,AlveoU280,VCU118}InstanceDeployManager``, and ``RHSResearchNitefuryIIInstanceDeployManager`` respectively. For example, to use the ``EC2InstanceDeployManager`` deploy platform class, you would write ``default_platform: EC2InstanceDeployManager``. ``default_simulation_dir`` @@ -941,7 +937,7 @@ When enabled, this appends the current users AWS user ID and region to the ``s3_ ``vitis.yaml`` bit builder recipe ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This bit builder recipe configures a build farm host to build an Vitis bitstream (FPGA bitstream called an ``xclbin``). +This bit builder recipe configures a build farm host to build an Vitis bitstream (FPGA bitstream called an ``xclbin``, packaged into a ``bitstream_tar``). ``device`` """""""""""""""""""""""""" @@ -955,9 +951,20 @@ Here is an example of this configuration file: ``xilinx_alveo_u250.yaml`` bit builder recipe ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This bit builder recipe configures a build farm host to build an Xilinx Alveo U250 bitstream. +This bit builder recipe configures a build farm host to build an Xilinx Alveo U250 bitstream, packaged into a ``bitstream_tar``. ``xilinx_alveo_u280.yaml`` bit builder recipe ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This bit builder recipe configures a build farm host to build an Xilinx Alveo U280 bitstream. +This bit builder recipe configures a build farm host to build an Xilinx Alveo U280 bitstream, packaged into a ``bitstream_tar``. + +``xilinx_vcu118.yaml`` bit builder recipe +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This bit builder recipe configures a build farm host to build an Xilinx VCU118 bitstream, packaged into a ``bitstream_tar``. + +``rhsresearch_nitefury_ii.yaml`` bit builder recipe +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This bit builder recipe configures a build farm host to build an RHS Research Nitefury II bitstream, packaged into a ``bitstream_tar``. + diff --git a/docs/Advanced-Usage/Manager/Manager-Tasks.rst b/docs/Advanced-Usage/Manager/Manager-Tasks.rst index 85898cb6..bc123e8c 100644 --- a/docs/Advanced-Usage/Manager/Manager-Tasks.rst +++ b/docs/Advanced-Usage/Manager/Manager-Tasks.rst @@ -23,21 +23,15 @@ Then, do platform-specific init steps for the given ``--platform``. * Prompt the user for email address and subscribe them to notifications for their own builds. * Setup the ``config_runtime.yaml`` and ``config_build.yaml`` files with AWS run/build farm arguments. - .. tab:: ``vitis`` + .. tab:: All other platforms - * Setup the ``config_runtime.yaml`` and ``config_build.yaml`` files with externally provisioned run/build farm arguments. - - .. tab:: ``xilinx_alveo_u250`` - - * Setup the ``config_runtime.yaml`` and ``config_build.yaml`` files with externally provisioned run/build farm arguments. - - .. tab:: ``xilinx_alveo_u280`` + This includes platforms such as: ``xilinx_alveo_u250``, ``xilinx_alveo_u280``, ``xilinx_vcu118``, and ``rhsresearch_nitefury_ii``. * Setup the ``config_runtime.yaml`` and ``config_build.yaml`` files with externally provisioned run/build farm arguments. You can re-run this whenever you want to get clean configuration files. -.. note:: In the case of ``f1``, you can just hit Enter when prompted for ``aws configure`` credentials and your email +.. note:: For ``f1``, you can just hit Enter when prompted for ``aws configure`` credentials and your email address, and both will keep your previously specified values. If you run this command by accident and didn't mean to overwrite your @@ -71,18 +65,7 @@ For each config, the build process entails: 9. [Local/AWS Infra] Submit the tar file to the AWS backend for conversion to an AFI 10. [Local] Wait for the AFI to become available, then notify the user of completion by email - .. tab:: Vitis - - 1. [Locally] Run the elaboration process for your hardware configuration - 2. [Locally] FAME-1 transform the design with MIDAS - 3. [Locally] Attach simulation models (I/O widgets, memory model, etc.) - 4. [Locally] Emit Verilog to run through the FPGA Flow - 5. Use a build farm configuration to launch/use build hosts for each configuration you want to build - 6. [Local/Remote] Prep build hosts, copy generated Verilog for hardware configuration to build instance - 7. [Local or Remote] Run Vitis Synthesis and P&R for the configuration - 8. [Local/Remote] Copy back all output generated by Vitis (including ``xclbin`` bitstream) - - .. tab:: Xilinx Alveo U250/U280 + .. tab:: XDMA-based On-Prem. 1. [Locally] Run the elaboration process for your hardware configuration 2. [Locally] FAME-1 transform the design with MIDAS @@ -93,14 +76,27 @@ For each config, the build process entails: 7. [Local or Remote] Run Vivado Synthesis and P&R for the configuration 8. [Local/Remote] Copy back all output generated by Vivado (including ``bit`` bitstream) + .. tab:: Vitis-based On-Prem. + + 1. [Locally] Run the elaboration process for your hardware configuration + 2. [Locally] FAME-1 transform the design with MIDAS + 3. [Locally] Attach simulation models (I/O widgets, memory model, etc.) + 4. [Locally] Emit Verilog to run through the FPGA Flow + 5. Use a build farm configuration to launch/use build hosts for each configuration you want to build + 6. [Local/Remote] Prep build hosts, copy generated Verilog for hardware configuration to build instance + 7. [Local or Remote] Run Vitis Synthesis and P&R for the configuration + 8. [Local/Remote] Copy back all output generated by Vitis (including the ``bitstream_tar`` containing the ``xclbin`` bitstream) + + + This process happens in parallel for all of the builds you specify. The command will exit when all builds are completed (but you will get notified as INDIVIDUAL builds complete if on F1) and indicate whether all builds passed or a build failed by the exit code. -.. Note:: **It is highly recommended that you either run this command in a ``screen`` or use - ``mosh`` to access the build instance. Builds will not finish if the manager is - killed due to disconnection to the instance.** +.. Note:: **It is highly recommended that you either run this command in a** ``screen`` **or use** + ``mosh`` **to access the manager instance. Builds will not finish if the manager is + killed due to ssh disconnection from the manager instance.** When you run a build for a particular configuration, a directory named ``LAUNCHTIME-CONFIG_TRIPLET-BUILD_NAME`` is created in ``firesim/deploy/results-build/``. @@ -113,18 +109,18 @@ This directory will contain: - ``AGFI_INFO``: Describes the state of the AFI being built, while the manager is running. Upon build completion, this contains the AGFI/AFI that was produced, along with its metadata. - ``cl_firesim:``: This directory is essentially the Vivado project that built the FPGA image, in the state it was in when the Vivado build process completed. This contains reports, stdout from the build, and the final tar file produced by Vivado. This also contains a copy of the generated verilog (``FireSim-generated.sv``) used to produce this build. - .. tab:: Vitis - - The Vitis project collateral that built the FPGA image, in the state it was in when the Vitis build process completed. - This contains reports, ``stdout`` from the build, and the final bitstream ``xclbin`` file produced by Vitis. - This also contains a copy of the generated verilog (``FireSim-generated.sv``) used to produce this build. - - .. tab:: Xilinx Alveo U250/U280 + .. tab:: XDMA-based On-Prem. The Vivado project collateral that built the FPGA image, in the state it was in when the Vivado build process completed. This contains reports, ``stdout`` from the build, and the final ``bitstream_tar`` bitstream/metadata file produced by Vivado. This also contains a copy of the generated verilog (``FireSim-generated.sv``) used to produce this build. + .. tab:: Vitis-based On-Prem. + + The Vitis project collateral that built the FPGA image, in the state it was in when the Vitis build process completed. + This contains reports, ``stdout`` from the build, and the final ``bitstream_tar`` produced from the Vitis-generated ``xclbin`` bitstream. + This also contains a copy of the generated verilog (``FireSim-generated.sv``) used to produce this build. + If this command is cancelled by a SIGINT, it will prompt for confirmation that you want to terminate the build instances. If you respond in the affirmative, it will move forward with the termination. @@ -142,6 +138,13 @@ build farm without prompting for confirmation if a SIGINT is received: ``firesim builddriver`` -------------------------------- +For FPGA-based simulations (when ``metasimulation_enabled`` is ``false`` in +``config_runtime.yaml``), this command will build the host-side simulation +driver, also without requiring any simulation hosts to be launched or reachable. +For complicated designs, running this before running ``firesim launchrunfarm`` +can reduce the time spent leaving FPGA hosts idling while waiting for +driver build. + For metasimulations (when ``metasimulation_enabled`` is ``true`` in ``config_runtime.yaml``), this command will build the entire software simulator without requiring any simulation hosts to be launched or reachable. @@ -150,19 +153,12 @@ your primary simulation tool while developing target RTL, since it allows you to run the Chisel build flow and iterate on your design without launching/setting up extra machines to run simulations. -For FPGA-based simulations (when ``metasimulation_enabled`` is ``false`` in -``config_runtime.yaml``), this command will build the host-side simulation -driver, also without requiring any simulation hosts to be launched or reachable. -For complicated designs, running this before running ``firesim launchrunfarm`` -can reduce the time spent leaving FPGA hosts idling while waiting for -driver build. - .. _firesim-tar2afi: ``firesim tar2afi`` ---------------------- -.. Warning:: Can only be used in the F1 case. +.. Note:: Can only be used for the F1 platform. This command can be used to run only steps 9 & 10 from an aborted ``firesim buildbitstream`` for F1 that has been manually corrected. ``firesim tar2afi`` assumes that you have a @@ -174,8 +170,8 @@ specifying an already existing LAUNCHTIME. This command will run for the configurations specified in :ref:`config-build` and :ref:`config-build-recipes` as with :ref:`firesim-buildbitstream`. It is likely that you may want -to comment out ``BUILD_NAME`` that successfully completed :ref:`firesim-buildbitstream` before -running this command. +to comment out build recipe names that successfully completed the :ref:`firesim-buildbitstream` process +before running this command. .. _firesim-shareagfi: @@ -183,7 +179,7 @@ running this command. ``firesim shareagfi`` ---------------------- -.. Warning:: Can only be used in the F1 case. +.. Note:: Can only be used for the F1 platform. This command allows you to share AGFIs that you have already built (that are listed in :ref:`config-hwdb`) with other users. It will take the @@ -212,9 +208,11 @@ These keys/values must match the same mapping structure as the ``args`` mapping. Overridden arguments override recursively such that all key/values present in the override args replace the default arguments given by the ``base_recipe``. In the case of sequences, a overridden sequence completely replaces the corresponding sequence in the default args. +Run Farm type-specific details: + .. tabs:: - .. tab:: AWS EC2 Run Farm Recipe (``aws_ec2.yaml``) + .. tab:: AWS EC2 An AWS EC2 run farm consists of AWS instances like ``f1.16xlarge``, ``f1.4xlarge``, ``f1.2xlarge``, and ``m4.16xlarge`` instances. Before you run the command, you define the number of each that you want in the ``recipe_arg_overrides`` section of @@ -233,7 +231,7 @@ by the ``base_recipe``. In the case of sequences, a overridden sequence complete the run farm are launched. See the documentation for ``config_runtime.yaml`` for more details on other arguments (see :ref:`config-runtime`). - .. tab:: Externally Provisioned Run Farm Recipe (``externally_provisioned.yaml``) + .. tab:: Externally Provisioned An Externally Provisioned run farm consists of a set of unmanaged run farm hosts given by the user. A run farm host is configured by a ``default_platform`` that determines how to run simulations on the host. @@ -272,16 +270,18 @@ This command potentially terminates some or all of the instances in the Run Farm in your ``config_runtime.yaml`` file by the ``run_farm`` ``base_recipe``, depending on the command line arguments you supply. +Run Farm type-specific details: + .. tabs:: - .. tab:: AWS EC2 Run Farm Recipe (``aws_ec2.yaml``) + .. tab:: AWS EC2 By default, running ``firesim terminaterunfarm`` will terminate ALL instances with the specified ``run_farm_tag``. When you run this command, it will prompt for confirmation that you want to terminate the listed instances. If you respond in the affirmative, it will move forward with the termination. - .. tab:: Externally Provisioned Run Farm Recipe (``externally_provisioned.yaml``) + .. tab:: Externally Provisioned By default, this run of ``firesim terminaterunfarm`` does nothing since externally managed run farm hosts should be managed by the user (and not by FireSim). @@ -430,10 +430,30 @@ the workloads, hardware configurations, and abstract host mappings for each simulation (and optionally, switch) in your design. These diagrams are located in ``firesim/deploy/generated-topology-diagrams/``, named after your topology. -Here is an example of such a diagram (click to expand/zoom): +Here is an example of such a diagram (click to expand/zoom, it will likely be +illegible without expanding): .. figure:: runcheck_example.png :scale: 50 % :alt: Example diagram from running ``firesim runcheck`` Example diagram for an 8-node cluster with one ToR switch + + +.. _firesim-enumeratefpgas: + +``firesim enumeratefpgas`` +----------------------------------- + +.. Note:: Can only be used for XDMA-based On-Premises platforms. + +This command should be run once for each on-premises Run Farm you plan to use +that contains XDMA-based FPGAs. When run, the command will generate a file +(``/opt/firesim-db.json``) on each Run Farm Machine in the run farm that +contains a mapping from the FPGA ID used for JTAG programming to the PCIe ID +used to run simulations for each FPGA attached to the machine. + +If you ever change the physical layout of a Run Farm Machine in your Run Farm +(e.g., which PCIe slot the FPGAs are attached to), you will need to re-run this +command. + diff --git a/docs/Advanced-Usage/Manager/Manager-URI-Paths.rst b/docs/Advanced-Usage/Manager/Manager-URI-Paths.rst index 4a74a021..59fd75cf 100644 --- a/docs/Advanced-Usage/Manager/Manager-URI-Paths.rst +++ b/docs/Advanced-Usage/Manager/Manager-URI-Paths.rst @@ -17,6 +17,7 @@ many URI protocols we do not test. Likewise, individual URI protocols will have their own requirements for specifying credentials. Documentation supplying credentials is provided by the individual protocol implementation. For example: + * `adlfs for Azure Data-Lake Gen1 and Gen2 `_ * `gcfs for Google Cloud Services `_ * `s3fs for AWS S3 `_ diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/RHS-Research-Nitefury-II.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/RHS-Research-Nitefury-II.rst index 88d1a0af..f450bddc 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/RHS-Research-Nitefury-II.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/RHS-Research-Nitefury-II.rst @@ -1,7 +1,6 @@ .. |fpga_name| replace:: RHS Research Nitefury II .. |hwdb_entry_name| replace:: ``nitefury_firesim_rocket_singlecore_no_nic`` .. |hwdb_entry_name_non_code| replace:: nitefury_firesim_rocket_singlecore_no_nic -.. |bit_file_type| replace:: ``bitstream_tar`` .. |builder_name| replace:: Xilinx Vivado .. |bit_builder_path| replace:: ``bit-builder-recipes/rhsresearch_nitefury_ii.yaml`` .. |vivado_with_version| replace:: Vivado 2022.1 diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-All-Bitstream-Template.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-All-Bitstream-Template.rst index 363004b9..e31954d1 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-All-Bitstream-Template.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-All-Bitstream-Template.rst @@ -59,9 +59,9 @@ that describes everything that happened, in-detail, during this run (this is a good file to send us if you encounter problems). The manager will also print an entry that can be added to ``config_hwdb.yaml`` so that the -bitstream can be used to run simulations. This entry will contain a |bit_file_type| key whose +bitstream can be used to run simulations. This entry will contain a ``bitstream_tar`` key whose value is the path to the final generated bitstream file. You can share generated bitstreams -with others by sharing the file listed in |bit_file_type| and the ``config_hwdb.yaml`` +with others by sharing the file listed in ``bitstream_tar`` and the ``config_hwdb.yaml`` entry for it. Now that you know how to generate your own FPGA image, you can modify the target-design diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Alveo-U250.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Alveo-U250.rst index add8af24..c2806924 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Alveo-U250.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Alveo-U250.rst @@ -1,7 +1,6 @@ .. |fpga_name| replace:: Xilinx Alveo U250 .. |hwdb_entry_name| replace:: ``alveo_u250_firesim_rocket_singlecore_no_nic`` .. |hwdb_entry_name_non_code| replace:: alveo_u250_firesim_rocket_singlecore_no_nic -.. |bit_file_type| replace:: ``bitstream_tar`` .. |builder_name| replace:: Xilinx Vivado .. |bit_builder_path| replace:: ``bit-builder-recipes/xilinx_alveo_u250.yaml`` .. |vivado_with_version| replace:: Vivado 2021.1 diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Alveo-U280.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Alveo-U280.rst index 0e9476aa..e8d615c4 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Alveo-U280.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Alveo-U280.rst @@ -1,7 +1,6 @@ .. |fpga_name| replace:: Xilinx Alveo U280 .. |hwdb_entry_name| replace:: ``alveo_u280_firesim_rocket_singlecore_no_nic`` .. |hwdb_entry_name_non_code| replace:: alveo_u280_firesim_rocket_singlecore_no_nic -.. |bit_file_type| replace:: ``bitstream_tar`` .. |builder_name| replace:: Xilinx Vivado .. |bit_builder_path| replace:: ``bit-builder-recipes/xilinx_alveo_u280.yaml`` .. |vivado_with_version| replace:: Vivado 2021.1 diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-VCU118.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-VCU118.rst index e9f93c32..23f64376 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-VCU118.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-VCU118.rst @@ -1,7 +1,6 @@ .. |fpga_name| replace:: Xilinx VCU118 .. |hwdb_entry_name| replace:: ``xilinx_vcu118_firesim_rocket_singlecore_4GB_no_nic`` .. |hwdb_entry_name_non_code| replace:: xilinx_vcu118_firesim_rocket_singlecore_4GB_no_nic -.. |bit_file_type| replace:: ``bitstream_tar`` .. |builder_name| replace:: Xilinx Vivado .. |bit_builder_path| replace:: ``bit-builder-recipes/xilinx_vcu118.yaml`` .. |vivado_with_version| replace:: Vivado 2019.1 diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Vitis.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Vitis.rst index 877ae227..32b38d0b 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Vitis.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Building-a-FireSim-Bitstream/Xilinx-Vitis.rst @@ -1,7 +1,6 @@ .. |fpga_name| replace:: Xilinx Vitis-enabled U250 .. |hwdb_entry_name| replace:: ``vitis_firesim_rocket_singlecore_no_nic`` .. |hwdb_entry_name_non_code| replace:: vitis_firesim_rocket_singlecore_no_nic -.. |bit_file_type| replace:: ``xclbin`` .. |builder_name| replace:: Xilinx Vitis .. |bit_builder_path| replace:: ``bit-builder-recipes/vitis.yaml`` diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/RHS-Research-Nitefury-II-FPGAs.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/RHS-Research-Nitefury-II-FPGAs.rst index 810c7e2c..884b3967 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/RHS-Research-Nitefury-II-FPGAs.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/RHS-Research-Nitefury-II-FPGAs.rst @@ -2,7 +2,6 @@ .. |fpga_name_short| replace:: RHS Research Nitefury II .. _fpga_name_short: https://rhsresearch.com/collections/rhs-public/products/nitefury-xilinx-artix-fpga-kit-in-nvme-ssd-form-factor-2280-key-m .. |flow_name| replace:: XDMA-based -.. |bit_type| replace:: ``bitstream_tar`` .. |build_type| replace:: Xilinx Vivado .. include:: Intro-Template.rst diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Alveo-U250-FPGAs.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Alveo-U250-FPGAs.rst index e4f64134..fa45029d 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Alveo-U250-FPGAs.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Alveo-U250-FPGAs.rst @@ -2,7 +2,6 @@ .. |fpga_name_short| replace:: Xilinx Alveo U250 .. _fpga_name_short: https://www.xilinx.com/products/boards-and-kits/alveo/u250.html .. |flow_name| replace:: XDMA-based -.. |bit_type| replace:: ``bitstream_tar`` .. |build_type| replace:: Xilinx Vivado .. _u250-standard-flow: diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Alveo-U280-FPGAs.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Alveo-U280-FPGAs.rst index 46b1835b..01168d00 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Alveo-U280-FPGAs.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Alveo-U280-FPGAs.rst @@ -2,7 +2,6 @@ .. |fpga_name_short| replace:: Xilinx Alveo U280 .. _fpga_name_short: https://www.xilinx.com/products/boards-and-kits/alveo/u280.html .. |flow_name| replace:: XDMA-based -.. |bit_type| replace:: ``bitstream_tar`` .. |build_type| replace:: Xilinx Vivado .. include:: Intro-Template.rst diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-VCU118-FPGAs.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-VCU118-FPGAs.rst index 30aa4e6a..e482cdbc 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-VCU118-FPGAs.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-VCU118-FPGAs.rst @@ -2,7 +2,6 @@ .. |fpga_name_short| replace:: Xilinx VCU118 .. _fpga_name_short: https://www.xilinx.com/products/boards-and-kits/vcu118.html .. |flow_name| replace:: XDMA-based -.. |bit_type| replace:: ``bitstream_tar`` .. |build_type| replace:: Xilinx Vivado .. include:: Intro-Template.rst diff --git a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Vitis-FPGAs.rst b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Vitis-FPGAs.rst index 7e6c7e03..90ddafe2 100644 --- a/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Vitis-FPGAs.rst +++ b/docs/Getting-Started-Guides/On-Premises-FPGA-Getting-Started/Xilinx-Vitis-FPGAs.rst @@ -2,7 +2,6 @@ .. |fpga_name_short| replace:: Xilinx Alveo U250 .. _fpga_name_short: https://www.xilinx.com/products/boards-and-kits/alveo/u250.html .. |flow_name| replace:: Vitis-based -.. |bit_type| replace:: ``xclbin`` .. |build_type| replace:: Xilinx Vitis .. warning:: ⚠️ **We highly recommend using the XDMA-based U250 flow instead of this @@ -22,8 +21,8 @@ and deploying simulations locally. #. **Single-node simulation guide**: This guide walks you through the - process of running one simulation locally consisting of a single - |fpga_name_short|, using our pre-built public FireSim |bit_type| bitstream. + process of running a simulation locally on a single + |fpga_name_short|, using a pre-built, public bitstream. #. **Building your own hardware designs guide (Chisel to FPGA Image)**: This guide walks you through the full process of taking Rocket Chip RTL