From f334d5799f881cec3df9c8b4d6824d4f6c7d5023 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Thu, 1 Apr 2021 16:21:16 -0700 Subject: [PATCH 01/14] Support 30MiB payloads - VCU118 FPGA --- fpga/src/main/resources/vcu118/sdboot/sd.c | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/fpga/src/main/resources/vcu118/sdboot/sd.c b/fpga/src/main/resources/vcu118/sdboot/sd.c index 47c87d5f..5f465ef6 100644 --- a/fpga/src/main/resources/vcu118/sdboot/sd.c +++ b/fpga/src/main/resources/vcu118/sdboot/sd.c @@ -8,10 +8,12 @@ #define DEBUG #include "kprintf.h" -#define MAX_CORES 8 - -// A sector is 512 bytes, so ((1 << 11) * 512) = 1 MiB -#define PAYLOAD_SIZE (16 << 11) +// Total payload in B +#define PAYLOAD_SIZE_B (30 << 20) // default: 30MiB +// A sector is 512 bytes, so (1 << 11) * 512B = 1 MiB +#define SECTOR_SIZE_B 512 +// Payload size in # of sectors +#define PAYLOAD_SIZE (PAYLOAD_SIZE_B / SECTOR_SIZE_B) // The sector at which the BBL partition starts #define BBL_PARTITION_START_SECTOR 34 @@ -168,9 +170,12 @@ static int copy(void) int rc = 0; dputs("CMD18"); + + kprintf("LOADING 0x%lxB PAYLOAD\r\n", PAYLOAD_SIZE_B); kprintf("LOADING "); - // John: Let's go slow until we get this working + // TODO: Can this be sped up? + // John Wright: Let's go slow until we get this working //REG32(spi, SPI_REG_SCKDIV) = (F_CLK / 16666666UL); REG32(spi, SPI_REG_SCKDIV) = (F_CLK / 5000000UL); if (sd_cmd(0x52, BBL_PARTITION_START_SECTOR, 0xE1) != 0x00) { @@ -182,7 +187,7 @@ static int copy(void) long n; crc = 0; - n = 512; + n = SECTOR_SIZE_B; while (sd_dummy() != 0xFE); do { uint8_t x = sd_dummy(); From 5a41c5d9ac20414c0071997e803ede13540f7fd9 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Thu, 1 Apr 2021 16:21:44 -0700 Subject: [PATCH 02/14] Use multi-clock config. frags to determine VCU118 clk freq --- fpga/src/main/scala/vcu118/Configs.scala | 15 +++++++-------- fpga/src/main/scala/vcu118/TestHarness.scala | 7 +++---- .../src/main/scala/config/AbstractConfig.scala | 1 - 3 files changed, 10 insertions(+), 13 deletions(-) diff --git a/fpga/src/main/scala/vcu118/Configs.scala b/fpga/src/main/scala/vcu118/Configs.scala index 8b17aa98..18f04de4 100644 --- a/fpga/src/main/scala/vcu118/Configs.scala +++ b/fpga/src/main/scala/vcu118/Configs.scala @@ -17,7 +17,7 @@ import sifive.fpgashells.shell.xilinx.{VCU118ShellPMOD, VCU118DDRSize} import testchipip.{SerialTLKey} -import chipyard.{BuildSystem, ExtTLMem} +import chipyard.{BuildSystem, ExtTLMem, DefaultClockFrequencyKey} class WithDefaultPeripherals extends Config((site, here, up) => { case PeripheryUARTKey => List(UARTParams(address = BigInt(0x64000000L))) @@ -26,11 +26,10 @@ class WithDefaultPeripherals extends Config((site, here, up) => { }) class WithSystemModifications extends Config((site, here, up) => { - case PeripheryBusKey => up(PeripheryBusKey, site).copy(dtsFrequency = Some(site(FPGAFrequencyKey).toInt*1000000)) - case DTSTimebase => BigInt(1000000) + case DTSTimebase => BigInt((1e6).toLong) case BootROMLocated(x) => up(BootROMLocated(x), site).map { p => // invoke makefile for sdboot - val freqMHz = site(FPGAFrequencyKey).toInt * 1000000 + val freqMHz = (site(DefaultClockFrequencyKey) * 1e6).toLong val make = s"make -C fpga/src/main/resources/vcu118/sdboot PBUS_CLK=${freqMHz} bin" require (make.! == 0, "Failed to build bootrom") p.copy(hang = 0x10000, contentFileName = s"./fpga/src/main/resources/vcu118/sdboot/build/sdboot.bin") @@ -52,7 +51,9 @@ class WithVCU118Tweaks extends Config( new WithSystemModifications ++ // setup busses, use sdboot bootrom, setup ext. mem. size new chipyard.config.WithNoDebug ++ // remove debug module new freechips.rocketchip.subsystem.WithoutTLMonitors ++ - new freechips.rocketchip.subsystem.WithNMemoryChannels(1)) + new freechips.rocketchip.subsystem.WithNMemoryChannels(1) ++ + new WithFPGAFrequency(100) // default 100MHz freq +) class RocketVCU118Config extends Config( new WithVCU118Tweaks ++ @@ -64,9 +65,7 @@ class BoomVCU118Config extends Config( new WithVCU118Tweaks ++ new chipyard.MegaBoomConfig) -class WithFPGAFrequency(MHz: Double) extends Config((site, here, up) => { - case FPGAFrequencyKey => MHz -}) +class WithFPGAFrequency(fMHz: Double) extends chipyard.config.WithPeripheryBusFrequency(fMHz) class WithFPGAFreq25MHz extends WithFPGAFrequency(25) class WithFPGAFreq50MHz extends WithFPGAFrequency(50) diff --git a/fpga/src/main/scala/vcu118/TestHarness.scala b/fpga/src/main/scala/vcu118/TestHarness.scala index 45afe7f7..64ad3deb 100644 --- a/fpga/src/main/scala/vcu118/TestHarness.scala +++ b/fpga/src/main/scala/vcu118/TestHarness.scala @@ -17,12 +17,10 @@ import sifive.blocks.devices.uart._ import sifive.blocks.devices.spi._ import sifive.blocks.devices.gpio._ -import chipyard.{HasHarnessSignalReferences, HasTestHarnessFunctions, BuildTop, ChipTop, ExtTLMem, CanHaveMasterTLMemPort} +import chipyard.{HasHarnessSignalReferences, HasTestHarnessFunctions, BuildTop, ChipTop, ExtTLMem, CanHaveMasterTLMemPort, DefaultClockFrequencyKey} import chipyard.iobinders.{HasIOBinders} import chipyard.harness.{ApplyHarnessBinders} -case object FPGAFrequencyKey extends Field[Double](100.0) - class VCU118FPGATestHarness(override implicit val p: Parameters) extends VCU118ShellBasicOverlays { def dp = designParameters @@ -55,7 +53,8 @@ class VCU118FPGATestHarness(override implicit val p: Parameters) extends VCU118S harnessSysPLL := sysClkNode // create and connect to the dutClock - val dutClock = ClockSinkNode(freqMHz = dp(FPGAFrequencyKey)) + println(s"VCU118 FPGA Base Clock Freq: ${dp(DefaultClockFrequencyKey)} MHz") + val dutClock = ClockSinkNode(freqMHz = dp(DefaultClockFrequencyKey)) val dutWrangler = LazyModule(new ResetWrangler) val dutGroup = ClockGroup() dutClock := dutWrangler.node := dutGroup := harnessSysPLL diff --git a/generators/chipyard/src/main/scala/config/AbstractConfig.scala b/generators/chipyard/src/main/scala/config/AbstractConfig.scala index da84bd05..71526d71 100644 --- a/generators/chipyard/src/main/scala/config/AbstractConfig.scala +++ b/generators/chipyard/src/main/scala/config/AbstractConfig.scala @@ -45,7 +45,6 @@ class AbstractConfig extends Config( new chipyard.config.WithNoSubsystemDrivenClocks ++ // drive the subsystem diplomatic clocks from ChipTop instead of using implicit clocks new chipyard.config.WithInheritBusFrequencyAssignments ++ // Unspecified clocks within a bus will receive the bus frequency if set new chipyard.config.WithPeripheryBusFrequencyAsDefault ++ // Unspecified frequencies with match the pbus frequency (which is always set) - new chipyard.config.WithMemoryBusFrequency(100.0) ++ // Default 100 MHz mbus new chipyard.config.WithPeripheryBusFrequency(100.0) ++ // Default 100 MHz pbus new freechips.rocketchip.subsystem.WithJtagDTM ++ // set the debug module to expose a JTAG port new freechips.rocketchip.subsystem.WithNoMMIOPort ++ // no top-level MMIO master port (overrides default set in rocketchip) From 2cfd930a32a3589714486a95550eedfc7cadeb20 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Fri, 2 Apr 2021 16:43:23 -0700 Subject: [PATCH 03/14] Bump FireMarshal for prototype targets --- software/firemarshal | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/software/firemarshal b/software/firemarshal index aa8e6aa8..0ada8d84 160000 --- a/software/firemarshal +++ b/software/firemarshal @@ -1 +1 @@ -Subproject commit aa8e6aa8714d46b74917ebaa91333f5727e34599 +Subproject commit 0ada8d84e2b2826a70a1ecf9dde01426d52d2475 From be13781a1c9711bb392f42491f569e0022b0ab17 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Fri, 2 Apr 2021 16:43:59 -0700 Subject: [PATCH 04/14] Set both MBUS/PBUS in configs | Add simple check for correct clocks --- fpga/src/main/scala/vcu118/Configs.scala | 8 +++++++- fpga/src/main/scala/vcu118/TestHarness.scala | 9 ++++++++- .../chipyard/src/main/scala/config/AbstractConfig.scala | 1 + 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/fpga/src/main/scala/vcu118/Configs.scala b/fpga/src/main/scala/vcu118/Configs.scala index 18f04de4..9da3ae1e 100644 --- a/fpga/src/main/scala/vcu118/Configs.scala +++ b/fpga/src/main/scala/vcu118/Configs.scala @@ -40,12 +40,15 @@ class WithSystemModifications extends Config((site, here, up) => { // DOC include start: AbstractVCU118 and Rocket class WithVCU118Tweaks extends Config( + // harness binders new WithUART ++ new WithSPISDCard ++ new WithDDRMem ++ + // io binders new WithUARTIOPassthrough ++ new WithSPIIOPassthrough ++ new WithTLIOPassthrough ++ + // other configuration new WithDefaultPeripherals ++ new chipyard.config.WithTLBackingMemory ++ // use TL backing memory new WithSystemModifications ++ // setup busses, use sdboot bootrom, setup ext. mem. size @@ -65,7 +68,10 @@ class BoomVCU118Config extends Config( new WithVCU118Tweaks ++ new chipyard.MegaBoomConfig) -class WithFPGAFrequency(fMHz: Double) extends chipyard.config.WithPeripheryBusFrequency(fMHz) +class WithFPGAFrequency(fMHz: Double) extends Config( + new chipyard.config.WithPeripheryBusFrequency(fMHz) ++ + new chipyard.config.WithMemoryBusFrequency(fMHz) +) class WithFPGAFreq25MHz extends WithFPGAFrequency(25) class WithFPGAFreq50MHz extends WithFPGAFrequency(50) diff --git a/fpga/src/main/scala/vcu118/TestHarness.scala b/fpga/src/main/scala/vcu118/TestHarness.scala index 64ad3deb..33161b68 100644 --- a/fpga/src/main/scala/vcu118/TestHarness.scala +++ b/fpga/src/main/scala/vcu118/TestHarness.scala @@ -17,7 +17,7 @@ import sifive.blocks.devices.uart._ import sifive.blocks.devices.spi._ import sifive.blocks.devices.gpio._ -import chipyard.{HasHarnessSignalReferences, HasTestHarnessFunctions, BuildTop, ChipTop, ExtTLMem, CanHaveMasterTLMemPort, DefaultClockFrequencyKey} +import chipyard.{HasHarnessSignalReferences, HasTestHarnessFunctions, BuildTop, ChipTop, ExtTLMem, CanHaveMasterTLMemPort, DefaultClockFrequencyKey, HasReferenceClockFreq} import chipyard.iobinders.{HasIOBinders} import chipyard.harness.{ApplyHarnessBinders} @@ -135,4 +135,11 @@ class VCU118FPGATestHarnessImp(_outer: VCU118FPGATestHarness) extends LazyRawMod _outer.topDesign match { case d: HasIOBinders => ApplyHarnessBinders(this, d.lazySystem, d.portMap) } + + // check the top-level reference clock is equal to the default + // non-exhaustive since you need all ChipTop clocks to equal the default + _outer.topDesign match { + case d: HasReferenceClockFreq => require(d.refClockFreqMHz == p(DefaultClockFrequencyKey)) + case _ => + } } diff --git a/generators/chipyard/src/main/scala/config/AbstractConfig.scala b/generators/chipyard/src/main/scala/config/AbstractConfig.scala index 71526d71..da84bd05 100644 --- a/generators/chipyard/src/main/scala/config/AbstractConfig.scala +++ b/generators/chipyard/src/main/scala/config/AbstractConfig.scala @@ -45,6 +45,7 @@ class AbstractConfig extends Config( new chipyard.config.WithNoSubsystemDrivenClocks ++ // drive the subsystem diplomatic clocks from ChipTop instead of using implicit clocks new chipyard.config.WithInheritBusFrequencyAssignments ++ // Unspecified clocks within a bus will receive the bus frequency if set new chipyard.config.WithPeripheryBusFrequencyAsDefault ++ // Unspecified frequencies with match the pbus frequency (which is always set) + new chipyard.config.WithMemoryBusFrequency(100.0) ++ // Default 100 MHz mbus new chipyard.config.WithPeripheryBusFrequency(100.0) ++ // Default 100 MHz pbus new freechips.rocketchip.subsystem.WithJtagDTM ++ // set the debug module to expose a JTAG port new freechips.rocketchip.subsystem.WithNoMMIOPort ++ // no top-level MMIO master port (overrides default set in rocketchip) From 985faa4c8e9608a80889afdd5a838a3fed9e8470 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Sat, 3 Apr 2021 12:55:27 -0700 Subject: [PATCH 05/14] Small comment updates + cleanup --- fpga/src/main/resources/vcu118/sdboot/sd.c | 5 ++--- fpga/src/main/scala/vcu118/Configs.scala | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/fpga/src/main/resources/vcu118/sdboot/sd.c b/fpga/src/main/resources/vcu118/sdboot/sd.c index 5f465ef6..f1bdb61e 100644 --- a/fpga/src/main/resources/vcu118/sdboot/sd.c +++ b/fpga/src/main/resources/vcu118/sdboot/sd.c @@ -171,11 +171,10 @@ static int copy(void) dputs("CMD18"); - kprintf("LOADING 0x%lxB PAYLOAD\r\n", PAYLOAD_SIZE_B); + kprintf("LOADING 0x%xB PAYLOAD\r\n", PAYLOAD_SIZE_B); kprintf("LOADING "); - // TODO: Can this be sped up? - // John Wright: Let's go slow until we get this working + // TODO: Speed up SPI freq. (breaks between these two values) //REG32(spi, SPI_REG_SCKDIV) = (F_CLK / 16666666UL); REG32(spi, SPI_REG_SCKDIV) = (F_CLK / 5000000UL); if (sd_cmd(0x52, BBL_PARTITION_START_SECTOR, 0xE1) != 0x00) { diff --git a/fpga/src/main/scala/vcu118/Configs.scala b/fpga/src/main/scala/vcu118/Configs.scala index 9da3ae1e..47a22dcf 100644 --- a/fpga/src/main/scala/vcu118/Configs.scala +++ b/fpga/src/main/scala/vcu118/Configs.scala @@ -69,7 +69,7 @@ class BoomVCU118Config extends Config( new chipyard.MegaBoomConfig) class WithFPGAFrequency(fMHz: Double) extends Config( - new chipyard.config.WithPeripheryBusFrequency(fMHz) ++ + new chipyard.config.WithPeripheryBusFrequency(fMHz) ++ // assumes using PBUS as default freq. new chipyard.config.WithMemoryBusFrequency(fMHz) ) From 565ef2eb3cbf0265a9fe36d0e497af12612b8f0d Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Sat, 3 Apr 2021 12:57:10 -0700 Subject: [PATCH 06/14] First commit of docs [ci skip] --- docs/Prototyping/VCU118.rst | 77 +++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/docs/Prototyping/VCU118.rst b/docs/Prototyping/VCU118.rst index 7f8f2cb9..0ad7bed7 100644 --- a/docs/Prototyping/VCU118.rst +++ b/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=/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. From e159c4f6a7087b55e9e4dd1789d04109f05c58bd Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Sat, 3 Apr 2021 13:48:58 -0700 Subject: [PATCH 07/14] 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). From 436c235b1710839b04d0acd30e1250db7ba40164 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Tue, 6 Apr 2021 12:24:07 -0700 Subject: [PATCH 08/14] Bump FireMarshal --- software/firemarshal | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/software/firemarshal b/software/firemarshal index 0ada8d84..8d9f7184 160000 --- a/software/firemarshal +++ b/software/firemarshal @@ -1 +1 @@ -Subproject commit 0ada8d84e2b2826a70a1ecf9dde01426d52d2475 +Subproject commit 8d9f71841e2215292c6fef663a98d4715998c047 From 8ed61d6a7ddce8a9c53ba34737177ce2a8802c9c Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Wed, 7 Apr 2021 12:13:41 -0700 Subject: [PATCH 09/14] Bump FireMarshal --- software/firemarshal | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/software/firemarshal b/software/firemarshal index 8d9f7184..22f9101d 160000 --- a/software/firemarshal +++ b/software/firemarshal @@ -1 +1 @@ -Subproject commit 8d9f71841e2215292c6fef663a98d4715998c047 +Subproject commit 22f9101d456f36d9580bd3327a1613e39812d06d From b152bbd0d4a1b092717762e281310fe9603eb4c3 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Mon, 12 Apr 2021 11:02:23 -0700 Subject: [PATCH 10/14] Update grammer issues a bit --- docs/Prototyping/VCU118.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/Prototyping/VCU118.rst b/docs/Prototyping/VCU118.rst index ee343d2d..1fb4fcf9 100644 --- a/docs/Prototyping/VCU118.rst +++ b/docs/Prototyping/VCU118.rst @@ -69,12 +69,12 @@ The following steps describe how to build and run buildroot Linux on the prototy Building Linux with FireMarshal ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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). +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 (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. +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``: .. code-block:: shell @@ -83,8 +83,8 @@ To make building this type of Linux binary easy, we will use the FireMarshal pla .. Note:: Refer to the FireMarshal docs on more ways to set the board differently through environment variables and more. -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. +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). .. code-block:: shell @@ -92,7 +92,7 @@ To make building this type of Linux binary easy, we will use the FireMarshal pla ./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"! + 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``). @@ -120,7 +120,8 @@ Additionally, these instructions assume you are using Linux with ``sudo`` privil Change the default partition alignment to `1` so you can write to sector `34`. Do this with the `l` command. -3. Create the new GPT with `o`. Click yes on all the prompts. +3. Create the new GPT with `o`. + Click yes on all the prompts. 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). From 9cee20ecc10105010f2cf1684aa815262da4245f Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Tue, 13 Apr 2021 22:23:03 -0700 Subject: [PATCH 11/14] Address review comments --- docs/Prototyping/VCU118.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/Prototyping/VCU118.rst b/docs/Prototyping/VCU118.rst index 1fb4fcf9..6cfa9f32 100644 --- a/docs/Prototyping/VCU118.rst +++ b/docs/Prototyping/VCU118.rst @@ -47,8 +47,8 @@ After the harness is created, the ``BundleBridgeSource``'s must be connected to This is done with harness binders and io binders (see ``fpga/src/main/scala/vcu118/HarnessBinders.scala`` and ``fpga/src/main/scala/vcu118/IOBinders.scala``). For more information on harness binders and io binders, refer to :ref:`Customization/IOBinders:IOBinders and HarnessBinders`. -Introduction to the Bringup Platform ------------------------------------- +Introduction to the Bringup Design +---------------------------------- An example of a more complicated design used for Chipyard test chips can be viewed in ``fpga/src/main/scala/vcu118/bringup/``. This example extends the default test harness and creates new ``Overlays`` to connect to a DUT (connected to the FMC port). @@ -59,8 +59,8 @@ 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 Basic and Bringup Platforms ----------------------------------------------- +Running Linux on VCU118 Designs +------------------------------- 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). @@ -69,7 +69,7 @@ The following steps describe how to build and run buildroot Linux on the prototy Building Linux with FireMarshal ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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). +Since the prototype currently does not have a block device setup for it, 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 (see :ref:`fire-marshal` on the initial setup). @@ -79,13 +79,14 @@ To make building this type of Linux binary easy, we will use the FireMarshal pla .. code-block:: shell + # this assumes you do not have a `marshal-config.yaml` file already setup echo "board-dir : 'boards/prototype'" > $PATH_TO_FIREMARSHAL/marshal-config.yaml .. Note:: Refer to the FireMarshal docs on more ways to set the board differently through environment variables and more. 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). + This workload has basic support for GPIO and SPI drivers (in addition to the default UART driver) but you can build off it in different workloads (refer to FireMarshal docs on workload inheritance). .. code-block:: shell @@ -105,7 +106,7 @@ Setting up the SDCard ~~~~~~~~~~~~~~~~~~~~~ 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. +The 1st partition will be used to store the Linux binary (created with FireMarshal or other means) while the 2nd partition will store a file system that can be accessed from the DUT. 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). 1. Wipe the GPT on the card using ``gdisk``. From 1dd2698e112557115762b15c12444f322f2cab64 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Tue, 13 Apr 2021 22:30:35 -0700 Subject: [PATCH 12/14] Update ref in chip communication docs. --- docs/Advanced-Concepts/Chip-Communication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Advanced-Concepts/Chip-Communication.rst b/docs/Advanced-Concepts/Chip-Communication.rst index 6e8d2c0e..b63a3885 100644 --- a/docs/Advanced-Concepts/Chip-Communication.rst +++ b/docs/Advanced-Concepts/Chip-Communication.rst @@ -222,4 +222,4 @@ The following image shows this flow: .. image:: ../_static/images/chip-bringup.png In fact, this exact type of bringup setup is what the following section discusses: -:ref:`Prototyping/VCU118:Introduction to the Bringup Platform`. +:ref:`Prototyping/VCU118:Introduction to the Bringup Design`. From 325f65e4dfcad7be0e9ae80e31d3140caee4563e Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Wed, 14 Apr 2021 11:21:33 -0700 Subject: [PATCH 13/14] Apply suggestions from code review Co-authored-by: alonamid --- docs/Prototyping/VCU118.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/Prototyping/VCU118.rst b/docs/Prototyping/VCU118.rst index 6cfa9f32..9cdedc37 100644 --- a/docs/Prototyping/VCU118.rst +++ b/docs/Prototyping/VCU118.rst @@ -84,7 +84,7 @@ To make building this type of Linux binary easy, we will use the FireMarshal pla .. Note:: Refer to the FireMarshal docs on more ways to set the board differently through environment variables and more. -3. Next, build the workload (a.k.a buildroot Linux) with nodisk with FireMarshal. +3. Next, build the workload (a.k.a buildroot Linux) in FireMarshal with the ``nodisk`` option flag. 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 (in addition to the default UART driver) but you can build off it in different workloads (refer to FireMarshal docs on workload inheritance). @@ -92,7 +92,7 @@ To make building this type of Linux binary easy, we will use the FireMarshal pla ./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. +.. Note:: Using the "board" FireMarshal functionality allows any child workload depending on the ``br-base.json`` workload specification to target a "prototype" platform rather than FireChip platform. 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. @@ -107,7 +107,7 @@ Setting up the SDCard 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 store a file system that can be accessed from the DUT. -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). +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). 1. Wipe the GPT on the card using ``gdisk``. Use the `z` command to zap everything. @@ -126,11 +126,11 @@ Additionally, these instructions assume you are using Linux with ``sudo`` privil 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. + For the type, search for the `apfs` type and use the hex number given. 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. + For the type, search for the `hfs` and use the hex number given. 6. Write the changes using `w`. @@ -162,4 +162,4 @@ To interact with Linux via the UART console, you can connect to the serial port 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). +Once connected, you should see the binary being loaded as well as Linux output (in some cases you might need to reset the DUT). From 39c37563664255e7c27253adb0674e409ca420e8 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Wed, 14 Apr 2021 11:24:19 -0700 Subject: [PATCH 14/14] Update VCU118.rst --- docs/Prototyping/VCU118.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Prototyping/VCU118.rst b/docs/Prototyping/VCU118.rst index 9cdedc37..ece3ac82 100644 --- a/docs/Prototyping/VCU118.rst +++ b/docs/Prototyping/VCU118.rst @@ -96,7 +96,7 @@ To make building this type of Linux binary easy, we will use the FireMarshal pla 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``). + This is done by using FireMarshal's ``install`` feature which will produce a ``*-flat`` binary in the ``$PATH_TO_FIREMARSHAL/images`` directory (in our case ``br-base-bin-nodisk-flat``) from the previously built Linux binary (``br-base-bin-nodisk``). .. code-block:: shell