From 50dfe03278c906fbbbb853a35440b17c0a7d89c3 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 12:30:48 -0700 Subject: [PATCH] talk about fesvr and combine with dtm/jtag [skip ci] --- docs/Advanced-Usage/Chip-Communication.rst | 76 ++++++++++++++++++++++ docs/Advanced-Usage/DTM-Debugging.rst | 47 ------------- docs/Advanced-Usage/index.rst | 2 +- 3 files changed, 77 insertions(+), 48 deletions(-) create mode 100644 docs/Advanced-Usage/Chip-Communication.rst delete mode 100644 docs/Advanced-Usage/DTM-Debugging.rst diff --git a/docs/Advanced-Usage/Chip-Communication.rst b/docs/Advanced-Usage/Chip-Communication.rst new file mode 100644 index 00000000..8f31d931 --- /dev/null +++ b/docs/Advanced-Usage/Chip-Communication.rst @@ -0,0 +1,76 @@ +.. _chip-communication: + +Communicating with the Chip/DUT +=============================== + +What good is a chip if it can't communicate with the outside world? Chipyard designs communicate to the outside world in +one of two ways: + +* using the Front-End Server (FESVR) +* using Rocket Chip's JTAG/DTM interface. + +Debugging with the Front-End Server (FESVR) +------------------------------------------- + +By default, Chipyard simulations are setup to use the Front-End Server (FESVR) and extra infrastructure to bringup the DUT. However, FESVR can also be used to +bringup a DUT/Chip when a tapeout is completed. FESVR is a C++ library that gives a simple API to reset, send messages, and run programs on a DUT. +It can be added used simulators (VCS, Verilator, FireSim) as well as in a bringup sequence for a taped out chip. + +In the case of a simulator like VCS/Verilator, FESVR functions are converted into Tethered Serial Interface (TSI) commands. +These TSI commands are simple R/W commands that are able to probe the DUT's memory space. In simulation, these TSI commands connect to +a ``SimSerial`` (located in the ``generators/testchipip`` project) simulation C++ class that is added to simulation. This ``SimSerial`` +device sends the TSI command to the DUT which contains a ``SerialAdapter`` (located in the ``generators/testchipip`` project) that converts +the TSI commands to TileLink requests. In simulation, FESVR resets the DUT, and writes into memory the test program. This is currently the fastest +mechanism to simulate the DUT. + +In the case of a chip tapeout bringup, FESVR is used as a library ... + +to a main C++ that is run to communicate to a physical chip. In this case, FESVR is normally modified to specify the communication +medium (i.e. send message with TSI over pins in a particular protocol). + +Debugging with DTM/JTAG +----------------------- + +Chipyard is not setup to use the Debug Test Module (DTM) to bringup the core. +This is because the DTM executes a small loop of code to write the test binary byte-wise into memory +while the default ``SimSerial``/``SerialAdapter``/``FESVR`` interface directly writes to memory. +However, if you want to use JTAG, you must do the following steps to setup a DTM enabled system. + +Creating a DTM/JTAG Config +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, a DTM config must be created for the system that you want to create. +This involves specifying the SoC top-level to add a DTM as well as configuring that DTM to use JTAG. + +.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala + :language: scala + :start-after: DOC include start: JtagRocket + :end-before: DOC include end: JtagRocket + +In this example, the ``WithDTMTop`` mixin specifies that the top-level SoC will instantiate a DTM. +The ``WithJtagDTM`` will configure that instantiated DTM to use JTAG as the bringup method (note: this can be removed if you want a DTM-only bringup). +The rest of the mixins specify the rest of the system (cores, accelerators, etc). + +Starting the DTM Simulation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After creating the config, call the ``make`` command like the following: + +.. code-block:: bash + + cd sims/verilator + # or + cd sims/vcs + + make CONFIG=DTMBoomConfig TOP=TopWithDTM MODEL=TestHarnessWithDTM + +In this example, this will use the config that you previously specified, as well as set the other parameters that are needed to satisfy the build system. +After that point, you should have a JTAG enabled simulation that you can attach to using OpenOCD and GDB! + +Debugging with JTAG +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please refer to the following resources on how to debug with JTAG. + +* https://github.com/chipsalliance/rocket-chip#-debugging-with-gdb +* https://github.com/riscv/riscv-isa-sim#debugging-with-gdb diff --git a/docs/Advanced-Usage/DTM-Debugging.rst b/docs/Advanced-Usage/DTM-Debugging.rst deleted file mode 100644 index 787a73ab..00000000 --- a/docs/Advanced-Usage/DTM-Debugging.rst +++ /dev/null @@ -1,47 +0,0 @@ -Debugging with DTM/JTAG -=============================== - -By default, Chipyard is not setup to use the Debug Test Module (DTM) to bringup the core. -Instead, Chipyard uses TSI commands to bringup the core (which normally results in a faster simulation). -TSI simulations use the SimSerial interface to directly write the test binary into memory, while the DTM -executes a small loop of code to write the test binary byte-wise into memory. -However, if you want to use JTAG, you must do the following steps to setup a DTM enabled system. - -Creating a DTM/JTAG Config -------------------------------------------- - -First, a DTM config must be created for the system that you want to create. -This involves specifying the SoC top-level to add a DTM as well as configuring that DTM to use JTAG. - -.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala - :language: scala - :start-after: DOC include start: JtagRocket - :end-before: DOC include end: JtagRocket - -In this example, the ``WithDTMTop`` mixin specifies that the top-level SoC will instantiate a DTM. -The ``WithJtagDTM`` will configure that instantiated DTM to use JTAG as the bringup method (note: this can be removed if you want a DTM-only bringup). -The rest of the mixins specify the rest of the system (cores, accelerators, etc). - -Starting the DTM Simulation -------------------------------------------- - -After creating the config, call the ``make`` command like the following: - -.. code-block:: bash - - cd sims/verilator - # or - cd sims/vcs - - make CONFIG=DTMBoomConfig TOP=TopWithDTM MODEL=TestHarnessWithDTM - -In this example, this will use the config that you previously specified, as well as set the other parameters that are needed to satisfy the build system. -After that point, you should have a JTAG enabled simulation that you can attach to using OpenOCD and GDB! - -Debugging with JTAG -------------------------------------------------------- - -Please refer to the following resources on how to debug with JTAG. - -* https://github.com/chipsalliance/rocket-chip#-debugging-with-gdb -* https://github.com/riscv/riscv-isa-sim#debugging-with-gdb diff --git a/docs/Advanced-Usage/index.rst b/docs/Advanced-Usage/index.rst index 2a8824b2..4864ce7a 100644 --- a/docs/Advanced-Usage/index.rst +++ b/docs/Advanced-Usage/index.rst @@ -8,5 +8,5 @@ They expect you to know about Chisel, Parameters, Configs, etc. :maxdepth: 2 :caption: Advanced Usage: - DTM-Debugging + Chip-Communication Resources