Miscellaneous Tips
=============================

.. _fsimcluster-aws-panel:

Add the ``fsimcluster`` column to your AWS management console
----------------------------------------------------------------

Once you've deployed a simulation once with the manager, the AWS management console
will allow you to add a custom column that will allow you to see at-a-glance
which FireSim run farm an instance belongs to.

To do so, click the gear in the top right of the AWS management console. From
there, you should see a checkbox for ``fsimcluster``. Enable it to see the column.

FPGA Dev AMI Remote Desktop Setup
-----------------------------------

To Remote Desktop into your manager instance, you must do the following:

.. code-block:: bash

    curl https://s3.amazonaws.com/aws-fpga-developer-ami/1.5.0/Scripts/setup_gui.sh -o /home/centos/src/scripts/setup_gui.sh
    sudo sed -i 's/enabled=0/enabled=1/g' /etc/yum.repos.d/CentOS-CR.repo
    /home/centos/src/scripts/setup_gui.sh
    # keep manager paramiko compatibility
    sudo pip2 uninstall gssapi


See

https://forums.aws.amazon.com/message.jspa?messageID=848073#848073

and

https://forums.aws.amazon.com/ann.jspa?annID=5710


Experimental Support for SSHing into simulated nodes and accessing the internet from within simulations
-------------------------------------------------------------------------------------------------------
This is assuming that you are simulating a 1-node networked cluster. These instructions
will let you both ssh into the simulated node and access the outside internet from within
the simulated node:

1. Set your config files to simulate a 1-node networked cluster (``example_1config``)
2. Run ``firesim launchrunfarm && firesim infrasetup`` and wait for them to complete
3. cd to ``firesim/target-design/switch/``
4. Go into the newest directory that is prefixed with ``switch0-``
5. Edit the ``switchconfig.h`` file so that it looks like this:

.. code-block:: c

    // THIS FILE IS MACHINE GENERATED. SEE deploy/buildtools/switchmodelconfig.py

    #ifdef NUMCLIENTSCONFIG
    #define NUMPORTS 2
    #define NUMDOWNLINKS 2
    #define NUMUPLINKS 0
    #endif
    #ifdef PORTSETUPCONFIG
    ports[0] = new ShmemPort(0, "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", false);
    ports[1] = new SSHPort(1);

    #endif

    #ifdef MACPORTSCONFIG
    uint16_t mac2port[3]  {1, 2, 0};
    #endif


6. Run ``make`` then ``cp switch switch0``
7. Run ``scp switch0 YOUR_RUN_FARM_INSTANCE_IP:switch_slot_0/switch0``
8. On the RUN FARM INSTANCE, run:

.. code-block:: bash

    sudo ip tuntap add mode tap dev tap0 user $USER
    sudo ip link set tap0 up
    sudo ip addr add 172.16.0.1/16 dev tap0
    sudo ifconfig tap0 hw ether 8e:6b:35:04:00:00
    sudo sysctl -w net.ipv6.conf.tap0.disable_ipv6=1


9. Run ``firesim runworkload``. Confirm that the node has booted to the login prompt in the fsim0 screen.

10. To ssh into the simulated machine, you will need to first ssh onto the Run Farm instance, then ssh into the IP address of the simulated node (172.16.0.2), username ``root``. You should also prefix with TERM=linux to get backspace to work correctly: So:

.. code-block:: bash

    ssh YOUR_RUN_FARM_INSTANCE_IP
    # from within the run farm instance:
    TERM=linux ssh root@172.16.0.2


11. To also be able to access the internet from within the simulation, run the following
on the RUN FARM INSTANCE:

.. code-block:: bash

    sudo sysctl -w net.ipv4.ip_forward=1
    export EXT_IF_TO_USE=$(ifconfig -a | sed 's/[ \t].*//;/^\(lo:\|\)$/d' | sed 's/[ \t].*//;/^\(tap0:\|\)$/d' | sed 's/://g')
    sudo iptables -A FORWARD -i $EXT_IF_TO_USE -o tap0 -m state --state RELATED,ESTABLISHED -j ACCEPT
    sudo iptables -A FORWARD -i tap0 -o $EXT_IF_TO_USE -j ACCEPT
    sudo iptables -t nat -A POSTROUTING -o $EXT_IF_TO_USE -j MASQUERADE


12. Then run the following in the simulation:

.. code-block:: bash

    route add default gw 172.16.0.1 eth0
    echo "nameserver 8.8.8.8" >> /etc/resolv.conf
    echo "nameserver 8.8.4.4" >> /etc/resolv.conf


At this point, you will be able to access the outside internet, e.g. ``ping google.com`` or ``wget google.com``.


Navigating the FireSim Codebase
---------------------------------

This is a large codebase with tons of dependencies, so navigating it can be
difficult. By default, a ``tags`` file is generated when you run
``./build-setup.sh`` which aids in jumping around the codebase. This file is
generated by Exuberant Ctags and many editors support using this file to jump
around the codebase. You can also regenerate the ``tags`` file if you make code changes
by running ``./gen-tags.sh`` in your FireSim repo.

For example, to use these tags to jump around the codebase in ``vim``, add the following to
your ``.vimrc``:

.. code-block:: bash

    set tags=tags;/


Then, you can move the cursor over something you want to jump to and hit
``ctrl-]`` to jump to the definition and ``ctrl-t`` to jump back out. E.g. in
top-level configurations in FireSim, you can jump all the way down through the
Rocket Chip codebase and even down to Chisel.

Using FireSim CI
----------------

For more information on how to deal with the FireSim CI and how to run FPGA simulations in the CI,
refer to the the ``CI_README.md`` under the ``.github/`` directory.

How to view AWS build logs when AGFI build fails
---------------------------------------------------------

There are times when we want to view Vivado logs when a bitstream build fails (especially when a bitstream build fails
while the manager is printing out ``pending``).
The AWS AGFI creation backend stores these logs in storage servers called S3 buckets.
The following steps will guide you on how to copy these logs from the bucket to your manager instance:

1. Go to your AWS console.

2. Select "View all services".

3. Under "Storage", select "S3".

4. On the left panel, select "Buckets".

5. Now select the bucket that you created.

See 
https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html
for the bucket naming style.
The bucket name is defined in ``firesim/deploy/bit-builder-recipes/f1.yaml``

6. Under "logs/agfi-<somenumber>", you will see "<date and time>_vivado.log". Select it and copy the S3 URI.

7. Now, go back to your manager instance and run ``aws s3 cp <URI that you just copied> some_descriptive_name.log``.

Now you should be able to view the Vivado log using your favorite text editor.