From 4824662323876d09398356ebc9eaeb4b16bb6e8e Mon Sep 17 00:00:00 2001
From: Tynan McAuley <tynan@galois.com>
Date: Thu, 11 Feb 2021 16:21:36 -0800
Subject: [PATCH] docs: Document hart ID ordering

---
 docs/Customization/Heterogeneous-SoCs.rst | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/Customization/Heterogeneous-SoCs.rst b/docs/Customization/Heterogeneous-SoCs.rst
index 380ccb10..7e31108b 100644
--- a/docs/Customization/Heterogeneous-SoCs.rst
+++ b/docs/Customization/Heterogeneous-SoCs.rst
@@ -56,6 +56,29 @@ If this is used earlier in the configuration sequence, then MultiRoCC does not w
 
 This config fragment can be changed to put more accelerators on more cores by changing the arguments to cover more ``hartId``'s (i.e. ``WithMultiRoCCHwacha(0,1,3,6,...)``).
 
+Since config fragments are applied from right-to-left (or bottom-to-top as they are formatted here), the right-most config fragment specifying a core (which is ``freechips.rocketchip.subsystem.WithNBigCores`` in the example above) gets the first hart ID.
+Consider this config:
+
+.. code-block:: scala
+
+    class RocketThenBoomHartIdTestConfig extends Config(
+      new boom.common.WithNLargeBooms(2) ++
+      new freechips.rocketchip.subsystem.WithNBigCores(3) ++
+      new chipyard.config.AbstractConfig)
+
+This specifies an SoC with three Rocket cores and two BOOM cores.
+The Rocket cores would have hart IDs 0, 1, and 2, while the BOOM cores would have hard IDs 3 and 4.
+On the other hand, consider this config which reverses the order of those two fragments:
+
+.. code-block:: scala
+
+    class BoomThenRocketHartIdTestConfig extends Config(
+      new freechips.rocketchip.subsystem.WithNBigCores(3) ++
+      new boom.common.WithNLargeBooms(2) ++
+      new chipyard.config.AbstractConfig)
+
+This also specifies an SoC with three Rocket cores and two BOOM cores, but because the BOOM config fragment is evaluated before the Rocket config fragment, the hart IDs are reversed.
+The BOOM cores would have hart IDs 0 and 1, while the Rocket cores would have hard IDs 2, 3, and 4.
 
 .. [1] Note, in this section "core" and "tile" are used interchangeably but there is subtle distinction between a "core" and "tile" ("tile" contains a "core", L1D/I$, PTW).
     For many places in the documentation, we usually use "core" to mean "tile" (doesn't make a large difference but worth the mention).