Documentation: Heterogeneous SoCs

[tymcauley]

Impact: documentation

Tell us about your environment:
Chipyard Version: 1.4.0

In the Heterogenous SoCs documentation page, I ran into a few confusing points.

Issue 1

In the "Creating a Rocket and BOOM System" section, the docs say:

The following example shows a dual core BOOM with a single core Rocket.

And then it includes the DualBoomAndRocket fragment from HeteroConfigs.scala, which looks like this:

// DOC include start: DualBoomAndRocket
class DualLargeBoomAndDualRocketConfig extends Config(
  new boom.common.WithNLargeBooms(2) ++                   // add 2 boom cores
  new freechips.rocketchip.subsystem.WithNBigCores(2) ++  // add 2 rocket cores
  new chipyard.config.AbstractConfig)
// DOC include end: DualBoomAndRocket

That looks as expected (although the config has 2 rocket cores, rather than the expected single core), but when I look at that example in the ReadTheDocs page, I see the LargeBoomAndHwachaRocketConfig config rather than DualLargeBoomAndDualRocketConfig. Not entirely sure what's wrong there. Do you see the same issue?

Issue 2

In the "Assigning Accelerators to Specific Tiles with MultiRoCC" section, the docs say:

An example is shown below with two BOOM cores, and one Rocket tile with a RoCC accelerator (Hwacha) attached.

And then it includes the DualBoomAndRocketOneHwacha fragment, but that config doesn't actually describe 2 BOOM cores and a Rocket core, it looks like this:

// DOC include start: DualBoomAndRocketOneHwacha
class LargeBoomAndHwachaRocketConfig extends Config(
  new chipyard.config.WithMultiRoCC ++                                  // support heterogeneous rocc
  new chipyard.config.WithMultiRoCCHwacha(1) ++                         // put hwacha on hart-1 (rocket)
  new hwacha.DefaultHwachaConfig ++                                     // set default hwacha config keys
  new boom.common.WithNLargeBooms(1) ++                                 // add 1 boom core
  new freechips.rocketchip.subsystem.WithNBigCores(1) ++                // add 1 rocket core
  new chipyard.config.AbstractConfig)
// DOC include end: DualBoomAndRocketOneHwacha

So it just has 1 BOOM core and 1 Rocket core. Since people might be using this config, should we just create a new DualLargeBoomAndHwachaRocketConfig config, and point this doc fragment to that new config?

Issue 3

Related to the previous issue, the docs say:

The WithMultiRoCCHwacha config fragment assigns a Hwacha accelerator to a particular hartId (in this case, the hartId of 2 corresponds to the Rocket core).

However, the WithMultiRoCCHwacha fragment uses a hart ID of 1. So, that should be fixed when Issue 2 is resolved. Still, that brings up a general point of confusion: in a heterogeneous config like this, how to I map hart IDs to the different cores? I don't think that mapping is explained. Presumably the ordering of the core config fragments affects this mapping, so that should probably be documented.

Once these questions are sorted out, I'm happy to submit a PR to resolve this.

[alonamid]

I suspect these issues are copy-paste errors when updating the documentation reference guards in the source code (DOC include start and DOC include end).
The names in the guards should match the config names they are guarding

[tymcauley]

Alright, I've taken care of the first two issues in #796, but I'm still unclear on number 3. How does core config fragment ordering affect hart numbering for those cores? Is there an easy way I can inspect that after building a config?

[tymcauley]

All questions answered in #796, this issue can safely be closed once that PR is merged.

[alonamid]

Merged in #796 . Thank you!