From 12d4e7d8372c0b4efd357d5b4feeb0596206651b Mon Sep 17 00:00:00 2001 From: Howard Mao Date: Wed, 25 Sep 2019 11:24:08 -0700 Subject: [PATCH 1/7] add section on IceNet [ci skip] --- docs/Generators/IceNet.rst | 73 +++++++++++++++++++++++++++++ docs/Generators/index.rst | 1 + docs/_static/images/nic-design.png | Bin 0 -> 20566 bytes 3 files changed, 74 insertions(+) create mode 100644 docs/Generators/IceNet.rst create mode 100644 docs/_static/images/nic-design.png diff --git a/docs/Generators/IceNet.rst b/docs/Generators/IceNet.rst new file mode 100644 index 00000000..2b3ac596 --- /dev/null +++ b/docs/Generators/IceNet.rst @@ -0,0 +1,73 @@ +IceNet +====== + +IceNet is a library of Chisel designs related to networking. The main component +of IceNet is IceNIC, a network interface controller that is used primarily +in `FireSim `_. A diagram of IceNet's microarchitecture +is shown below. + +.. image:: ../_static/images/nic-design.png + +There are four basic parts of the NIC: the :ref:`Controller`, which takes requests +from and sends responses to the CPU; the :ref:`Send Path`, which reads data from +memory and sends it out to the network; the :ref:`Receive Path`, which receives +data from the network and writes it to memory; and, optionally, +the :ref:`Pause Handler`, which generates Ethernet pause frames for the purpose +of flow control. + +Controller +---------- + +The controller exposes a set of MMIO registers to the CPU. The device driver +writes to registers to request that packets be sent or to provide memory +locations to write received data to. Upon the completion of a send request or +packet receive, the controller sends an interrupt to the CPU, which clears +the completion by reading from another register. + +Send Path +--------- + +The send path begins at the reader, which takes requests from the controller +and reads the data from memory. + +Since TileLink responses can come back out-of-order, we use a reservation +queue to reorder responses so that the packet data can be sent out in the +proper order. + +The packet data then goes to an arbiter, which can arbitrate access to the +outbound network interface between the NIC and one or more "tap in" interfaces, +which come from other hardware modules that may want to send Ethernet packets. +By default, there are no tap in interfaces, so the arbiter simply passes +the output of the reservation buffer through. + +Receive Path +------------ + +The receive path begins with the packet buffer, which buffers data coming +in from the network. If there is insufficient space in the buffer, it will +drop data at packet granularity to ensure that the NIC does not deliver +incomplete packets. + +From the packet buffer, the data can optionally go to a network tap, which +examines the Ethernet header and select packets to be redirected from the NIC +to external modules through one or more "tap out" interfaces. By default, there +are no tap out interfaces, so the data will instead go directly to the writer, +which writes the data to memory and then sends a completion to the controller. + +Pause Handler +------------- + +IceNIC can be configured to have pause handler, which sits between the +send and receive paths and the Ethernet interface. This module tracks the +occupancy of the receive packet buffer. If it sees the buffer filling up, it +will send an `Ethernet pause frame `_ +out to the network to block further packets from being sent. If the NIC receives +an Ethernet pause frame, the pause handler will block sending from the NIC. + +Linux Driver +------------ + +The default Linux configuration provided by `firesim-software `_ +contains an IceNet driver. If launch a FireSim image that has IceNIC on it, +the driver will automatically detect the device, and you will be able to use +the full Linux networking stack in userspace. diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index a147ffeb..a3594666 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -15,3 +15,4 @@ The following pages introduce the generators integrated with the Chipyard framew BOOM Hwacha RocketChip + IceNet diff --git a/docs/_static/images/nic-design.png b/docs/_static/images/nic-design.png new file mode 100644 index 0000000000000000000000000000000000000000..0ebaf0e0a41424ffeefa8c722e82888b00125a07 GIT binary patch literal 20566 zcmV*ZKvutrP)>H|%z6)mkgo0(>7VZDAAIUiN%?(N$v-~z>$e=a+O>|_wbz=*95zWPD8t=d2T7oA@(>Qp5{ z`TO(r%}(i3W&iPf_wUaW;rxX0>wlj=7U<8>Enz50I3UAo{dGyzDXtm{58j$^6i9{O@%;mdBrHK3A)zbIR z@8(IY`Z-#g@fC+=zn@sm-uKq|nOEjn|32?ysP=Ejjrobi77q|V$ddeG@kgZcGx!$8 z10%yQR4%64D+>liOVToRliU7U*;({<>MR;O7f~RE{3~hekVsX9? z--qwZ_vJfS5R2k$42On0<4`Zc2tqr_RAF#5s+qw{cCX4qWg*$C^X6(yB*%4OWV4tJ zt8a2La(y`>1QqDCm;RPF;1!Zp@}t_uF4P+%a)Wo8@J{hbFM#8J`e7UjYvf~zZlloPoUAD;m{4}tcHoT2R6ZE(S=m{sF(uHtd43=+Hr1F=>juA(Csi=J z(>|!ifrR2r2 z7M?92u{hGAY!(n$WM~nKg_^8*dFBs7-O$B`leSQ_o4VUf-usmg-voY>K`%hCuIxa; zhi3=f4z_%0_E%;A*D-qDUq!M{f2FqaAuflB2go01!r?dZxWM6pzDxEl$GRH%+NK;O zUqW#2r7ZC%IDY{1fEof+2eFFXP~*sPUwIRyN(MTNE1X|(**0$T{ODU)DCET8y9a!G zN||2DB3f>x+{xjzP*6E%!sm{2N`6KkoK-UW52mvq_nDzk?3`$cREbV5T4vH@A_RK`AqQ@v^{bO=RQEaF9G6xkI=c^0cE)S$f- zl|ipzMb|B0t7vGM1w#~inY^5HmAL|9=Qj&Kl*5rsb}>$B8|a=xW75m2t1LpZRH36= zfJQ2dfZ}-BZI{h4HwHJJ?6b;aARthD@U6Qz@p1R!1o%K&hblh$D9jQaODhLsw@A5o zcZtchUM_&T*GiC$Xt#v$o9D5k#9j46rNo}XtH3;gI!FVuBUKRKeo zI!3LNpDSuT2hCX(-l}j_ZPsh^nre&3mQi~@bP|rn?b^?J)l~r->a z)YrUKxs&|jk#?)9R2c^JIO=xlY(et}Y!;53UhRo3MhQHkdn#-~@!%kB%wnTO`k~{1 zL~7klpk=F@i6EjrYV&5*S5z^!6l%%-BZOgI9w|=Q#l}9zG_&h z!BHY$t~OvVif>W9XHy42xsyIZR5ssH8@{DhrL}4s-tUc>twGLBqqRL-BV`?5>5*Eu z+xnSwGOZ2xc})5H)YluZ}`b5LL>CrYzZ!{onPH)raYgRrC$U|J)x}KC6G3vq`H9}5{F<-B)e0{eL{~$<(LrDWt~ojyl7u~I*#-W z{5SF57~XhI{dJPseXkCrIGA0J$A$eKHV%b`Z7-JK)ZH$Y}#(>29$T)a=bf$6K2GlgJ__+HFC?5qc z0|B7b!U-;{2pi5g{L7mKjpA4(qSd(Mpx}?Q1$0S6Tl!17b?MhY4_g^UepQ6ul%P=M zf~<=g7-kNIEvU21>+&u&Vz$KMA!Ty(phr;I?7SD>5%{U%i)$<5e&{jIHlbGK%9iV( zfrtl3lYrA{#}In@mP>8`e6gYQ2qc(lUN}Mr*@y)72SWST-O|YtWJBk!#3sFSslei}xFey=cO(409QY6pa&LWb_yT^F<*4!SLZ7Efqz&rEa(inI#!&M;XJG=i^T>YIJM}G|o_-M!Hc1J(h%VP=LSaJ^H zD3-%#2#5H6x7(&39Dv)*$(y#VIftPQZE?6Q9oYULH;FhJen3S1o^goQ7)K5)jy>XV zrXY(KYzhrAc_&?G#U}PNzuZE6F50i04l|H&KeRk2Xb)m>vq3KN=5gn`GID!3RS3=JbHyZG_~HTpB#|~?J3SWIKO_`VT^G`XTsHBBS}%R?J?3-?^ODya zC|@{z^q7h6dqkmMC=v8BgrrzNNzoAybO*MEd(RD#6Y`QqqdA!~0UfOlC7=Pbq*%1_ zTQ$fhg))ht#i2%S-*Jz_k(6yj`WNky1jtLRinRa$M72poK~#9!?Y)1@G}~R+_xbwX zt815HnAa341@)r2KtvUhT;?TU8O31c5m0=g#@bhx)U8ZG^VI4;rBb?&M5DOsKeMeA zCx5xSYGnjgf_8OriG!ms6NejN4CymmKy7GBo|Ub(N&!<>27Rmkyhx~_uqa8Z$}w8PBYbX|oE ziSWCwgYt0EwNyn>l-AHus&e7TMr#&bbyeDBZImjeCLOc^Ax6|pOL^cNr*GwDyAsN+ z7%_4uV{sei3MJ_Js$3fDqtv+g%fqoY9g?oAswn%=qjBib`j&(YfjKeY5fI3z(c1Qq zm`T@{<+4~4spe|&mqhqnn|QYZ6-BA$Sba-|3`w~$lj1mJD5)8B-QtHxc--cPW1Pye45pML;J)}WG-x{Kgx{yT zNVI&``kL&%Ro}a4*0(|oSF&0|WVR6GBG9*uA`?UVXFN+q&VHsZS@!t1(@ zRsE#gyD&8DTkD@^W6V9=n9<-&QkN2w@B!dzMD zF^?GGaMRb7!?oVEbKg?BrJ+a_Po{Fem^7_?nJzb&%#0?t-I}H}+0asywlJx=VMZi9 z@&mA;ckSM{l#Xe%<1Zc&4m0MYB(UOlX!U*HqlZ;dDu@Xf^hFW}WUa=AzdWp(xSPxd4R8rm0~fJ1v%^$TJ^)uxqlbec{49k6cs z>g2;(2^D=eDwT*Y#X4+^yZBZ-!czABjMguOCW;=6F+?~9Jf_^+ zsuvjUGWBE}LJap+3du`_j!h~Zn$9zAQ=%foUK`?OinLThhU&&^F)EbkMzRa@%nV z3l76Q9%Ydl6*tsySFP`dQIUGNX|qVh#b8#u?BY4Gp9}*-40l!ERDV+Wdz6Ay>^V)7sX zE|4-YX=bILe{P7)mAC}JoS7;`Jv_uGqSo_~gbaz7E<;wnHMXy)EQ(cjT>hr|lgbh! z{2qCqs;*VcoTZnX5sYQiHuwvJHn5Y#fP$*UZJwu~;=U z*wnkUZ=Dw!C`CCojrZ5ZV@S4xeOx>uwb)aRg9b`bIw#-#&z#MrwCv?m96|q>g$MY*;y07FwzaF{9QeRVpf!W?(A zk@Ar@lLpMp6Z-@4iMZ*1ybA4G=ZLPQD#s>aZ+9QEYCW{i2-dmmv7WSJQKqznid5y; zOn|{^B+dqI$79N(SgqD85TF0N>pCblDpHjrvox4on3{?!V{W%*oB_c?^ombFb7d@> zcx{xL68Ff)|1jRmxAw_Vq0+gnfu{3M+r9c1HbD1_x*hdawpG` zguRM7bs*yM)xdXlT@Pi6>ZK|tq1FcIYGba+;f|ukVOpqZ`S=W_);#v?$lCRnyRL?^ zq_t71IO2;s3R8B(#79?V3h{}#G6IZvLX0or!KLbhJmCGif9B0&(kdVZje;i+*IWO@=;1~I6E=4Wu z>`}c`<+8~<1uPV`var>2_BI;m5iXBSnmO?@e@p&MybE|uTmULkm5auta$Rgi#reOJ zONioBcKv4#Hi=MLqBUFNt#;m;E;aS*-k-w8AKyCgt)tNTJF){1=TT7?e}`7?aBJ>p zC3j@y{&Z#Ta3!~?$sP8j72(;pqImwTQEE9@su2lUdSZ;tRq6W?F_CqA#ZLmmh3`fq z65;QV+qZt}xVf*u&Rx+?J9n2gZ8f*m&a3`AUv7f<-G=02o_n}TSvnn@lNNs`l${YK zrM!!8QtR)!+{sGr<=-j)2KX)RS8~r+a>q5f?Rs?Cit60w(hA33tuIgf)0&@Juaf

sH=P4?|; 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

  • pR}HK?zwGw>DDflV6+s|NMKoH|31=DmBE2_X)S|s_@Pmv8XOjXF zi3D3oax|KX7d%##WmM(7-4D}5B8jGb^*wW>1+K=H{%Z6H>h}eURpB(06_i2wAPv#4 z9XDY32_J@q#BQNw*hId6HVrZ|monrti9cHA)L4LwEp=_e*tmPhka6Y!q6^g+wx*=l zTPXM}sE?<}^oj7dT!EDaf!xeA0rXs9nvUJ`$`QGD;bqGE>zHx8=4sh=Y1R`M!;grA)-CO}0L!n$6aXy;8*39kaL;}m!;p%K zhkmnd>MurlBd0xS$lsv(9g!}Ltq?m2uuC#!TU~PRys=B&*QDm7&07P<@gMTWX;vr3 zCT;JT3`pD3HqFV+En@BaZ7pVz9U(8A#v@0W^0wBFeZ)nNEYE7o_{@FML}Nr%T31zDod>(Zau>zAz3cV68N{t<~TISs4oeNO05v4i2|8Ju z5hP4yx^<`~F@Lt#U!>mGBD>hZqrb^9Uj-NWD!S7BqkSHCxP#+2`3(IiZ7C)4CMME* z`T^J)*J{8Q?+cK91YthMe_0Aw40tXC%OQv|FuJ4xaQprTztj-8Xa6mg)>h_V@{4iW z5iXN+8R~0uUh<1i(3FID6G|vZB~OAQ$L4AhAe%ZL`&QG?$I`S6mUk(YW}bngq4o_kDSKoS{Y{X(?)jp7x{02NZ;nF0$W=Ul~&M8$<>o;G}HNxqP-d50Czi*(R`Zpg1|@6bKM z7QjO69bol<@+HO%4wdcL>v6CQCJnVCYFSSx)KRC8hgteZ!Jj1>#=hREkz)O}Qwg%e zm4w}WOAW7!H?Y?9aI_FE(Ik(By#Khmb%dk0_B>HppQ#>4_%Up6vQN)}E|*0}qWt56Xi;5zG3 z>r*C9e%*9LP-;3g!-Wl^W}F*TVzhQ=-ri^8jmst`-hru37zc-q!mxF+MRdp1Pi2d- zJEI2==6abwYPX!gM(@?w8z}LF9ER{~XYLZXMrgsUa?L*4Huo8& zm~iKv@nh+&*f2)MvW**b+pD6}^=sH9JTwy<7zLsE_+O5BtQts8TlPa1V{MFUXwU7t z-43E~r|Q3xeTM^rp>2_DF4CwJ>ejxyyQ!_T#8?dKem86MQ{ID&A11?C%RZ; zn~uV_2Bdh%NECsOE*9Z%zEDSvSQ@6V> zag?9;B`IAr^TJV%6YAoc&5}P4t0-wbA8eNc|Ftj$p_$u=Cvm2H+j3K)uPGERa<{)5 z4w(Mp>QPpb|677cFkC=t%CZ0HrPx&742`$*b-E2wx5H|O^1%0<;Y_zzEn!21;86Ru zZh$9RoOtDpNd$pCv*^r;)a-dZpR~T2+cGNpY*Fz&(r*Yp87*I@&MF!ZCLF6DPZfi& z^NQOtyQ~IhoO5{_M*k3xq&w${R&L&#AeD*y!=;hj7kBj2DzkQHijw|Na2|fg_mtQa zwqSi0;D}%77SMdayz@kH+tWd>S_>(#?C0&ZQBk28O6+#`O_@Md>iGdHWjcoqfG_Cf zW>pNyzzvelV$_?+LuYc$iJ8xHPY53cITM{?9HBhsgpl7JWZL^ zK~RDX22W_dP@oC1W2)+hDovM0>M8jn^eTjT!g-Dxwa9&LKy)`)^@m^Y#ExIV9h7xy zQoP@at|~pRww$nm5K4==uDC&DAq5&=HZk>OK}}Qtf@I&N$;~B&A`5AH{E}L3w+bAN zStwjPHhteTv1ZR17brk2qD&$owDk{X*R_jQhb^R&I`U8jwoYxDjW|q#K~0K$=Dv(R ze`()|_E9;3xtgu$&z~Ltrv2~VcUs*ak%(jQf((cWhZ z5?~T*;wII-!)x48CG!&syr)AiYz>~M8;6t+W^QruNbf&syt?0edJQHOz!oeA4~0Uwor5({XV)@Go>v5f zCCRR`bwgI$_G;T5Kv>MTLtf|+{Ym5z_dm(1OQ`BmaiH1PCeHhga#pN^k-6b6GK{&B z02|Effx%o%%DLUFGWmp((tn;g`8>HQV`0#I@lwl91- z!u&CHstP^I320FH$qwBW5^UaL`b$`hV2iDcYF`HIt`77)pYQx)D(hC0+?Q4rbP&&B z5m~Wy2sDCI zvR7GOU*9!mK|G#MQcEb=H6|?X2HNSj{^^nx*onX*jcQb}nawnI#ahCeu>NUjO2l! zlnydr^eFJqMzR$(NhCAdLVaUU*x{1Vu~1ET^{3AoPUil=RUCI98FwspX2c$M2*K#Jf8 zysIZ00<#bCyb=PKkVr68ktgZr)Vt3}&0rFYQU{{Us2JR342kMf1ng9R* literal 0 HcmV?d00001 From c8e846518058f4b34364b1f8ef041e64505dbeb3 Mon Sep 17 00:00:00 2001 From: Howard Mao Date: Wed, 25 Sep 2019 13:01:51 -0700 Subject: [PATCH 2/7] add Test Chip IP section [ci skip] --- docs/Generators/TestChipIP.rst | 51 ++++++++++++++++++++++++++++++++++ docs/Generators/index.rst | 1 + 2 files changed, 52 insertions(+) create mode 100644 docs/Generators/TestChipIP.rst diff --git a/docs/Generators/TestChipIP.rst b/docs/Generators/TestChipIP.rst new file mode 100644 index 00000000..cf4dc64b --- /dev/null +++ b/docs/Generators/TestChipIP.rst @@ -0,0 +1,51 @@ +Test Chip IP +============ + +Chipyard includes a Test Chip IP library which provides various hardware +widgets that may be useful when designing SoCs. This includes a :ref:`Serial Adapter`, +:ref:`Block Device Controller`, :ref:`TileLink SERDES`, and :ref:`TileLink Switcher`. + +Serial Adapter +-------------- + +The serial adapter is used by tethered test chips to communicate with the host +processor. An instance of RISC-V frontend server running on the host CPU +can send commands to the serial adapter to read and write data from the memory +system. The frontend server uses this functionality to load the test program +into memory and to poll for completion of the program. More information on +this can be found in :ref:`Chipyard Boot Process`. + +Block Device Controller +----------------------- + +The block device controller provides a generic interface for secondary storage. +This device is primarily used in FireSim to interface with a block device +software simulation model. The default Linux configuration in `firesim-software `_ + +TileLink SERDES +--------------- + +The TileLink SERDES in the Test Chip IP library allow TileLink memory requests +to be serialized so that they can be carried off chip through a serial link. +The five TileLink channels are multiplexed over two SERDES channels, one in +each direction. + +There are three different variants provided by the library, ``TLSerdes`` +exposes a manager interface to the chip, tunnels A, C, and E channels on +its outbound link, and tunnels B and D channels on its inbound link. ``TLDesser`` +exposes a client interface to the chip, tunnels A, C, and E on its inbound link, +and tunnels B and D on its outbound link. Finally, ``TLSerdesser`` exposes +both client and manager interface to the chip and can tunnel all channels in +both directions. + +TileLink Switcher +----------------- + +The TileLink switcher is used when the chip has multiple possible memory +interfaces and you would like to select which channels to map your memory +requests to at boot time. It exposes a client node, multiple manager nodes, +and a select signal. Depending on the setting of the select signal, requests +from the client node will be directed to one of the manager nodes. +The select signal must be set before any TileLink messages are sent and be +kept stable throughout the remainder of operation. It is not safe to change +the select signal once TileLink messages have begun sending. diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index a3594666..674decd7 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -16,3 +16,4 @@ The following pages introduce the generators integrated with the Chipyard framew Hwacha RocketChip IceNet + TestChipIP From 9dc0abb4854e6b626961aff7ff67771140350eee Mon Sep 17 00:00:00 2001 From: Howard Mao Date: Wed, 25 Sep 2019 16:41:32 -0700 Subject: [PATCH 3/7] explain how to add IceNet and TestChipIP hardware to design --- docs/Generators/IceNet.rst | 11 +++++++++++ docs/Generators/TestChipIP.rst | 12 ++++++++++++ 2 files changed, 23 insertions(+) diff --git a/docs/Generators/IceNet.rst b/docs/Generators/IceNet.rst index 2b3ac596..4dca3daa 100644 --- a/docs/Generators/IceNet.rst +++ b/docs/Generators/IceNet.rst @@ -71,3 +71,14 @@ The default Linux configuration provided by `firesim-software `_ +To add a block device to your design, add ``HasPeripheryBlockDevice`` to your +lazy module and ``HasPeripheryBlockDeviceModuleImp`` to the implementation. +Then add the ``WithBlockDevice`` config mixin to your configuration. + + TileLink SERDES --------------- @@ -38,6 +43,10 @@ and tunnels B and D on its outbound link. Finally, ``TLSerdesser`` exposes both client and manager interface to the chip and can tunnel all channels in both directions. +For an example of how to use the SERDES classes, take a look at the +``SerdesTest`` unit test in `the Test Chip IP unit test suite +`_. + TileLink Switcher ----------------- @@ -49,3 +58,6 @@ from the client node will be directed to one of the manager nodes. The select signal must be set before any TileLink messages are sent and be kept stable throughout the remainder of operation. It is not safe to change the select signal once TileLink messages have begun sending. + +For an example of how to use the switcher, take a look at the ``SwitcherTest`` +unit test in the `Test Chip IP unit tests `_. From 2f3c87dade24f918b07b27e3ed6c17140f8035cd Mon Sep 17 00:00:00 2001 From: Howard Mao Date: Wed, 25 Sep 2019 17:25:38 -0700 Subject: [PATCH 4/7] add explanation of LazyModule vs. LazyModuleImp [skip ci] --- .../Configs-Parameters-Mixins.rst | 17 +++++++++++++++-- docs/Generators/IceNet.rst | 13 ++++++++----- 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index 2d93f2b3..b1d6ebd0 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -80,16 +80,29 @@ This example shows a Rocket Chip based SoC that merges multiple system component .. code-block:: scala class MySoC(implicit p: Parameters) extends RocketSubsystem - with CanHaveMisalignedMasterAXI4MemPort + with CanHaveMasterAXI4MemPort with HasPeripheryBootROM with HasNoDebug with HasPeripherySerial with HasPeripheryUART with HasPeripheryIceNIC { - //Additional top-level specific instantiations or wiring + lazy val module = new MySoCModuleImp(this) } + class MySoCModuleImp(outer: MySoC) extends RocketSubsystemModuleImp(outer) + with CanHaveMasterAXI4MemPortModuleImp + with HasPeripheryBootROMModuleImp + with HasNoDebugModuleImp + with HasPeripherySerialModuleImp + with HasPeripheryUARTModuleImp + with HasPeripheryIceNICModuleImp + +There are two "cakes" here. One for the lazy module and one for the module +implementation. The lazy module defines all the logical connections between +generators and exchanges configuration information among them, while the +module implementation performs the actual Chisel RTL elaboration. + Mix-in --------------------------- diff --git a/docs/Generators/IceNet.rst b/docs/Generators/IceNet.rst index 4dca3daa..b520eb6c 100644 --- a/docs/Generators/IceNet.rst +++ b/docs/Generators/IceNet.rst @@ -3,8 +3,8 @@ IceNet IceNet is a library of Chisel designs related to networking. The main component of IceNet is IceNIC, a network interface controller that is used primarily -in `FireSim `_. A diagram of IceNet's microarchitecture -is shown below. +in `FireSim `_ for multi-node networked simulation. +A diagram of IceNet's microarchitecture is shown below. .. image:: ../_static/images/nic-design.png @@ -68,7 +68,7 @@ Linux Driver ------------ The default Linux configuration provided by `firesim-software `_ -contains an IceNet driver. If launch a FireSim image that has IceNIC on it, +contains an IceNet driver. If you launch a FireSim image that has IceNIC on it, the driver will automatically detect the device, and you will be able to use the full Linux networking stack in userspace. @@ -76,9 +76,12 @@ Configuration ------------- To add IceNIC to your design, add ``HasPeripheryIceNIC`` to your lazy module -and ``HasPeripheryIceNICModuleImp`` to the module implementation. +and ``HasPeripheryIceNICModuleImp`` to the module implementation. If you +are confused about the distinction between lazy module and module +implementation, refer to :ref:`Cake Pattern`. -Then add the ``WithIceNIC`` config mixin to your configuration. This mixin +Then add the ``WithIceNIC`` config mixin to your configuration. This will +define ``NICKey``, which IceNIC uses to determine its parameters. The mixin takes two arguments. The ``inBufFlits`` argument is the number of 64-bit flits that the input packet buffer can hold and the ``usePauser`` argument determines whether or not the NIC will have a pause handler. From 7cfac672c14759a0821aa6046b5136247adbba98 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Wed, 25 Sep 2019 19:34:47 -0700 Subject: [PATCH 5/7] Update docs/Chipyard-Basics/Configs-Parameters-Mixins.rst [skip ci] Co-Authored-By: Jerry Zhao --- .../Configs-Parameters-Mixins.rst | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index b1d6ebd0..1f726f51 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -103,7 +103,32 @@ implementation. The lazy module defines all the logical connections between generators and exchanges configuration information among them, while the module implementation performs the actual Chisel RTL elaboration. -Mix-in +In the MySoC example class, the "outer" ``MySoC`` instantiates the "inner" +``MySoCModuleImp`` as a lazy module. This delays immediate elaboration +of the module. The ``RocketSubsystem`` outer base class, as well as the +``HasPeripheryX`` outer traits contain code to perform high-level logical +connections. For example, the ``HasPeripherySerial`` outer trait contains code +to lazily instantiate the ``SerialAdapter``, and connect the SerialAdapter's +TileLink node to the frontbus. + +The ``ModuleImp`` classes and traits perform elaboration of real RTL. +For example, the ``HasPeripherySerialModuleImp`` trait physically connects +the ``SerialAdapter`` module, and instantiates queues. + +In the test harness, the SoC is elaborated with +``val dut = Module(LazyModule(MySoC))``. +After elaboration, the result will be a MySoC module, which contains a +SerialAdapter module (among others). + +From a high level, classes which extend LazyModule *must* reference +their module implementation through``lazy val module``, and they +*may* optionally reference other lazy modules (which will elaborate + as child modules in the module hierarchy). The "inner" modules + contain the implementation for the module, and may instantiate + other normal modules OR lazy modules (for nested Diplomacy + graphs, for example. This is very advanced). + + Mix-in --------------------------- A mix-in is a Scala trait, which sets parameters for specific system components, as well as enabling instantiation and wiring of the relevant system components to system buses. From d0e5a4068704c6ab65369caadfa9a2d1bd2d3068 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 20:02:16 -0700 Subject: [PATCH 6/7] slightly more clarity in the diplomacy example [skip ci] --- .../Configs-Parameters-Mixins.rst | 41 ++++++++++--------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index 1f726f51..864bd969 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -98,36 +98,37 @@ This example shows a Rocket Chip based SoC that merges multiple system component with HasPeripheryUARTModuleImp with HasPeripheryIceNICModuleImp -There are two "cakes" here. One for the lazy module and one for the module -implementation. The lazy module defines all the logical connections between -generators and exchanges configuration information among them, while the -module implementation performs the actual Chisel RTL elaboration. +There are two "cakes" here. One for the lazy module (ex. ``HasNoDebug``) and one for the lazy module +implementation (ex. ``HasNoDebugModuleImp`` where ``Imp`` refers to implementation). The lazy module defines +all the logical connections between generators and exchanges configuration information among them, while the +lazy module implementation performs the actual Chisel RTL elaboration. -In the MySoC example class, the "outer" ``MySoC`` instantiates the "inner" -``MySoCModuleImp`` as a lazy module. This delays immediate elaboration -of the module. The ``RocketSubsystem`` outer base class, as well as the -``HasPeripheryX`` outer traits contain code to perform high-level logical +In the MySoC example class, the "outer" ``MySoC`` instantiates the "inner" +``MySoCModuleImp`` as a lazy module implementation. This delays immediate elaboration +of the module until all logical connections are determined and all configuration information is exchanged. +The ``RocketSubsystem`` outer base class, as well as the +``HasPeripheryX`` outer traits contain code to perform high-level logical connections. For example, the ``HasPeripherySerial`` outer trait contains code -to lazily instantiate the ``SerialAdapter``, and connect the SerialAdapter's -TileLink node to the frontbus. +to lazily instantiate the ``SerialAdapter``, and connect the ``SerialAdapter``'s +TileLink node to the Front bus. The ``ModuleImp`` classes and traits perform elaboration of real RTL. For example, the ``HasPeripherySerialModuleImp`` trait physically connects -the ``SerialAdapter`` module, and instantiates queues. +the ``SerialAdapter`` module, and instantiates queues. -In the test harness, the SoC is elaborated with -``val dut = Module(LazyModule(MySoC))``. +In the test harness, the SoC is elaborated with +``val dut = Module(LazyModule(MySoC))``. After elaboration, the result will be a MySoC module, which contains a SerialAdapter module (among others). -From a high level, classes which extend LazyModule *must* reference -their module implementation through``lazy val module``, and they +From a high level, classes which extend LazyModule *must* reference +their module implementation through ``lazy val module``, and they *may* optionally reference other lazy modules (which will elaborate - as child modules in the module hierarchy). The "inner" modules - contain the implementation for the module, and may instantiate - other normal modules OR lazy modules (for nested Diplomacy - graphs, for example. This is very advanced). - +as child modules in the module hierarchy). The "inner" modules +contain the implementation for the module, and may instantiate +other normal modules OR lazy modules (for nested Diplomacy +graphs, for example). + Mix-in --------------------------- From 461829678edd10bf616db6fbbe0737e05f54b132 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 20:24:20 -0700 Subject: [PATCH 7/7] switch from no debug to peripheryserial [skip ci] --- docs/Chipyard-Basics/Configs-Parameters-Mixins.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index 864bd969..e83bc9e2 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -98,8 +98,8 @@ This example shows a Rocket Chip based SoC that merges multiple system component with HasPeripheryUARTModuleImp with HasPeripheryIceNICModuleImp -There are two "cakes" here. One for the lazy module (ex. ``HasNoDebug``) and one for the lazy module -implementation (ex. ``HasNoDebugModuleImp`` where ``Imp`` refers to implementation). The lazy module defines +There are two "cakes" here. One for the lazy module (ex. ``HasPeripherySerial``) and one for the lazy module +implementation (ex. ``HasPeripherySerialModuleImp`` where ``Imp`` refers to implementation). The lazy module defines all the logical connections between generators and exchanges configuration information among them, while the lazy module implementation performs the actual Chisel RTL elaboration.