First commit of docs [ci skip]

docs/Prototyping/VCU118.rst

@@ -58,3 +58,80 @@ The TSI Host Widget is used to interact with the DUT from the prototype over a S
 .. Note:: Remember that since whenever a new test harness is created (or the config changes, or the config packages changes, or...), you need to modify the make invocation.
     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
+-------------------------------
+
+Both the bringup and normal VCU118 platforms are setup to boot Linux loaded from the SPI SDCard.
+
+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.
+
+1. Setup FireMarshal
+2. Switch the FireMarshal "board" to target the prototype platform using ``marshal-config.yaml``
+
+```
+    echo "board-dir : \'boards/prototype\' > PATH_TO_FIREMARSHAL/marshal-config.yaml
+```
+
+This should allow you to use the ``br-base.json`` workload built for the prototype platform (includes GPIO/SPI drivers).
+
+3. Run ``./marshal -v -d build br-base.json`` to build the workload with initramfs.
+
+4. Install the workload ``./marshal -v -d install -t prototype br-base.json``. This will flatten the binary.
+
+.. note:: Feel free to modify and build off the `br-base.json` using normal FireMarshal functionality.
+
+Setting up the SDCard
+~~~~~~~~~~~~~~~~~~~~~
+
+The following instructions are for Linux but you can follow a similar set of steps on Mac (using `gpt`).
+
+Linux Instructions
+==================
+
+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).
+
+1. Wipe the GPT on the card.
+
+`sudo gdisk /dev/sdc`
+
+2. Use the `z` command to zap everything.
+
+`sudo gdisk /dev/sdc`
+
+3. Change the default partition alignment to `1` so you can write to sector `34`.
+Do this with the `l` command.
+
+4. Then create the new GPT with `o`. Click yes on all the prompts.
+
+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.
+
+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.
+
+7. Write the changes using `w`.
+
+8. Setup the filesystem on the 2nd partition using the following command:
+
+`sudo mkfs.hfs -v "Prototype Data" /dev/sdc2`
+
+Note that `sdc2` is used since it points to the 2nd partition.
+
+Transfer Linux to the SDCard
+============================
+
+Finally transfer the `-flat` binary generated by FireMarshal to the sdcard:
+
+`sudo dd if=<path-to-firemarshal>/br-base-bin-nodisk-flat of=/dev/sdc1`
+
+Note that `sdc1` points to the 1st partition.
+
+Additionally at this point you can mount the 2nd partition, add files, and mount that on the Linux on the prototype.