wu-arch/chipyard
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Cleanup docs for Linux on VCU118

Browse Source
This commit is contained in:
Abraham Gonzalez
2021-04-03 13:48:58 -07:00
parent 565ef2eb3c
commit e159c4f6a7
1 changed files with 68 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
docs/Prototyping/VCU118.rst
View File

@@ -59,79 +59,105 @@ The TSI Host Widget is used to interact with the DUT from the prototype over a S
For example, ``make SUB_PROJECT=vcu118 CONFIG=MyNewVCU118Config CONFIG_PACKAGE=this.is.my.scala.package bitstream``.
See :ref:`Prototyping/General:Generating a Bitstream` for information on the various make variables.
Running Linux with SDCard Setup
-------------------------------
Running Linux with Basic and Bringup Platforms
----------------------------------------------
Both the bringup and normal VCU118 platforms are setup to boot Linux loaded from the SPI SDCard.
As mentioned above, the default VCU118 harness is setup with a UART and a SPI SDCard.
These are utilized to both interact with the DUT (with the UART) and load in Linux (with the SDCard).
The following steps describe how to build and run buildroot Linux on the prototype platform.
Building Linux with FireMarshal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build Linux that will run on the VCU118 prototype, we will use the FireMarshal platform.
To understand FireMarshal in more depth, refer to it's documentation.
Since the prototype does not have a block device we build Linux with the rootfs built into the binary (otherwise known as "initramfs" or "nodisk" version of Linux).
To make building this type of Linux binary easy, we will use the FireMarshal platform (see :ref:`fire-marshal` for more information).
1. Setup FireMarshal
2. Switch the FireMarshal "board" to target the prototype platform using ``marshal-config.yaml``
1. Setup FireMarshal (see :ref:`fire-marshal` on the initial setup).
2. By default FireMarshal is setup to work with FireSim.
Instead we want to target the prototype platform.
This is done by switching the FireMarshal "board" from "firechip" to "prototype" using ``marshal-config.yaml``:
```
echo "board-dir : \'boards/prototype\' > PATH_TO_FIREMARSHAL/marshal-config.yaml
```
.. code-block:: shell
This should allow you to use the ``br-base.json`` workload built for the prototype platform (includes GPIO/SPI drivers).
echo "board-dir : 'boards/prototype'" > $PATH_TO_FIREMARSHAL/marshal-config.yaml
3. Run ``./marshal -v -d build br-base.json`` to build the workload with initramfs.
.. Note:: Refer to the FireMarshal docs on more ways to set the board differently through environment variables and more.
4. Install the workload ``./marshal -v -d install -t prototype br-base.json``. This will flatten the binary.
3. Next build the workload (a.k.a buildroot Linux) with nodisk with FireMarshal.
For the rest of these steps we will assume you are using the base ``br-base.json`` workload.
This workload has basic support for GPIO and SPI drivers but you can build off it in different workloads (refer to FireMarshal docs on workload inheritance).
.. note:: Feel free to modify and build off the `br-base.json` using normal FireMarshal functionality.
.. code-block:: shell
./marshal -v -d build br-base.json # here the -d indicates --nodisk or initramfs
.. Note:: Using the "board" FireMarshal functionality allows any child workload depending on ``br-base.json`` to use the "prototype" ``br-base.json`` rather than the FireChip version.
Thus you can re-use existing workloads that depend on ``br-base.json`` on the prototype platform by just changing the "board"!
4. The last step to generate the proper binary is to flatten it.
This is done by using FireMarshal's install feature and will produce a ``*-flat`` binary in the ``$PATH_TO_FIREMARSHAL/images`` directory (in our case ``br-base-bin-nodisk-flat``).
.. code-block:: shell
./marshal -v -d install -t prototype br-base.json
Setting up the SDCard
~~~~~~~~~~~~~~~~~~~~~
The following instructions are for Linux but you can follow a similar set of steps on Mac (using `gpt`).
These instructions assume that you have a spare uSDCard that can be loaded with Linux and other files using two partitions.
The 1st partition will be used to store the Linux binary (created with FireMarshal or other means) while the 2nd partition will be used to store miscellaneous files.
Additionally, these instructions assume you are using Linux with ``sudo`` privileges and ``gdisk`` but you can follow a similar set of steps on Mac (using ``gpt`` or another similar program).
Linux Instructions
==================
1. Wipe the GPT on the card using ``gdisk``.
Use the `z` command to zap everything.
For rest of these instructions, we assume the SDCard path is ``/dev/sdc`` (replace this with the path to your SDCard).
Use `gdisk` to put the binary on the SDCard.
The following steps use `/dev/sdc` as the path to the SD card (replace with your own path).
.. code-block:: shell
1. Wipe the GPT on the card.
sudo gdisk /dev/sdc
`sudo gdisk /dev/sdc`
2. The VCU118 bootrom assumes that the Linux binary to load into memory will be located on sector 34 of the SDCard.
Change the default partition alignment to `1` so you can write to sector `34`.
Do this with the `l` command.
2. Use the `z` command to zap everything.
3. Create the new GPT with `o`. Click yes on all the prompts.
`sudo gdisk /dev/sdc`
4. Create a 512MiB partition to store the Linux binary (this can be smaller but it must be larger than the size of the Linux binary).
Use `n` and select sector 34, with size `+1048576` (corresponding to 512MiB).
For the type search for the `apfs` type and use the hex number given.
3. Change the default partition alignment to `1` so you can write to sector `34`.
Do this with the `l` command.
5. Create a second partition to store any other files with the rest of the SDCard.
Use `n` and use the defaults for starting sector and overall size (expand the 2nd partition to the rest of the SDCard space).
For the type search for the `hfs` and use the hex number given.
4. Then create the new GPT with `o`. Click yes on all the prompts.
6. Write the changes using `w`.
5. Create a 512MiB partition to store the Linux payload (note this can be smaller but it must be larger than the size of the Linux payload).
Use `n` and select sector 34, with size `+1048576`.
For the type search for the `apfs` type and use the hex number given.
7. Setup the filesystem on the 2nd partition.
Note that the ``/dev/sdc2`` points to the 2nd partition.
Use the following command:
6. Create a second partition to store any other files with the rest of the SDCard.
Use `n` and use the defaults for starting sector and overall size.
For the type search for the `hfs` and use the hex number given.
.. code-block:: shell
7. Write the changes using `w`.
sudo mkfs.hfs -v "PrototypeData" /dev/sdc2
8. Setup the filesystem on the 2nd partition using the following command:
Transfer and Run Linux from the SDCard
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`sudo mkfs.hfs -v "Prototype Data" /dev/sdc2`
After you have a Linux boot binary and the SDCard is setup properly (1st partition at sector 34), you can transfer the binary to the 1st SDCard partition.
In this example, we generated a ``br-base-bin-nodisk-flat`` from FireMarshal and we will load it using ``dd``.
Note that ``sdc1`` points to the 1st partition (remember to change the ``sdc`` to your own SDCard path).
Note that `sdc2` is used since it points to the 2nd partition.
.. code-block:: shell
Transfer Linux to the SDCard
============================
sudo dd if=$PATH_TO_FIREMARSHAL/br-base-bin-nodisk-flat of=/dev/sdc1
Finally transfer the `-flat` binary generated by FireMarshal to the sdcard:
If you want to add files to the 2nd partition, you can also do this now.
`sudo dd if=<path-to-firemarshal>/br-base-bin-nodisk-flat of=/dev/sdc1`
After loading the SDCard with Linux and potentially other files, you can program the FPGA and plug in the SDCard.
To interact with Linux via the UART console, you can connect to the serial port (in this case called ``ttyUSB1``) using something like ``screen``:
Note that `sdc1` points to the 1st partition.
.. code-block:: shell
Additionally at this point you can mount the 2nd partition, add files, and mount that on the Linux on the prototype.
screen -S FPGA_UART_CONSOLE /dev/ttyUSB1 115200
Once connected you should see the binary being loaded as well as Linux output (in some cases you might need to reset the DUT).