From e159c4f6a7087b55e9e4dd1789d04109f05c58bd Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Sat, 3 Apr 2021 13:48:58 -0700 Subject: [PATCH] Cleanup docs for Linux on VCU118 --- docs/Prototyping/VCU118.rst | 110 ++++++++++++++++++++++-------------- 1 file changed, 68 insertions(+), 42 deletions(-) diff --git a/docs/Prototyping/VCU118.rst b/docs/Prototyping/VCU118.rst index 0ad7bed7..ee343d2d 100644 --- a/docs/Prototyping/VCU118.rst +++ b/docs/Prototyping/VCU118.rst @@ -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=/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).