Merge pull request #19 from ucb-ucie/scaladoc

Setup scaladoc + tweak doc-comments

Author: ethanwu10

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: coursier/cache-action@v6
+      - uses: coursier/setup-action@v1
+        with:
+          jvm: 17
+          apps: sbtn
+      - name: Build docs
+        run: |
+          sbt -v 'doc'
+      - name: Upload atifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./target/scala-2.13/api
+
+  deploy:
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

build.sbt

@@ -10,6 +10,8 @@ ThisBuild / scalacOptions := Seq(
   "-Xlint",
 )
 
+Compile / doc / scalacOptions += "-groups"
+
 val chiselVersion = "3.6.0"
 
 lazy val root = (project in file("."))

src/main/scala/Afe.scala

@@ -3,7 +3,9 @@ package edu.berkeley.cs.ucie.digital
 import chisel3._
 import chisel3.util._
 
-// The mainband pins exposed by a standard package UCIe module in one direction.
+/** The mainband pins exposed by a standard package UCIe module in one
+  * direction.
+  */
 class MainbandIo(lanes: Int = 16) extends Bundle {
   val data = Bits(lanes.W)
   val valid = Bool()
@@ -12,60 +14,100 @@ class MainbandIo(lanes: Int = 16) extends Bundle {
   val clkn = Clock()
 }
 
-// The sideband pins exposed by a standard package UCIe module in one direction.
+/** The sideband pins exposed by a standard package UCIe module in one
+  * direction.
+  */
 class SidebandIo extends Bundle {
   val data = Bool()
   val clk = Clock()
 }
 
-// The pins (mainband and sideband) exposed by a standard package UCIe module in one direction.
+/** The pins (mainband and sideband) exposed by a standard package UCIe module
+  * in one direction.
+  */
 class UnidirectionalIo(lanes: Int = 16) extends Bundle {
   val mainband = new MainbandIo(lanes)
   val sideband = new SidebandIo()
 }
 
-// The pins (mainband and sideband) exposed by a standard package UCIe module in both directions.
+/** The pins (mainband and sideband) exposed by a standard package UCIe module
+  * in both directions.
+  */
 class StandardPackageIo(lanes: Int = 16) extends Bundle {
   val tx = Output(new UnidirectionalIo(lanes))
   val rx = Input(new UnidirectionalIo(lanes))
 }
 
-// The sideband analog front-end (AFE) interface, from the perspective of the logical PHY layer.
-//
-// All signals in this interface are synchronous to the sideband clock (fixed at 800 MHz).
-// As a result, the sideband's `serializerRatio` likely will be different from the mainband's `serializerRatio`.
+/** The sideband analog front-end (AFE) interface, from the perspective of the
+  * logical PHY layer.
+  *
+  * All signals in this interface are synchronous to the sideband clock (fixed
+  * at 800 MHz). As a result, the sideband's `serializerRatio` likely will be
+  * different from the mainband's `serializerRatio`.
+  */
 class SidebandAfeIo(
     serializerRatio: Int = 1,
 ) extends Bundle {
-  // Data to transmit on the sideband.
-  // Output from the async FIFO.
+
+  /** Data to transmit on the sideband.
+    *
+    * Output from the async FIFO.
+    */
   val txData = Decoupled(Bits(serializerRatio.W))
-  // Data received on the sideband.
-  // Input to the async FIFO.
+
+  /** Data received on the sideband.
+    *
+    * Input to the async FIFO.
+    */
   val rxData = Flipped(Decoupled(Bits(serializerRatio.W)))
-  // Enable sideband receivers.
+
+  /** Enable sideband receivers. */
   val rxEn = Output(Bool())
 }
 
-// The mainband analog front-end (AFE) interface, from the perspective of the logical PHY layer.
-//
-// All signals in this interface are synchronous to the mainband AFE's digital clock,
-// which is produced by taking a high speed clock from a PLL
-// and dividing its frequency by `serializerRatio`.
-//
-// With half-rate clocking (1 data bit transmitted per UI; 1 UI = 0.5 clock cycles), the PLL clock
-// may be 2, 4, 6, 8, 12, or 16 GHz. With a serializer ratio of 16, this results in a 0.125-1 GHz
-// AFE digital clock.
+/** The mainband analog front-end (AFE) interface, from the perspective of the
+  * logical PHY layer.
+  *
+  * All signals in this interface are synchronous to the mainband AFE's digital
+  * clock, which is produced by taking a high speed clock from a PLL and
+  * dividing its frequency by `serializerRatio`.
+  *
+  * With half-rate clocking (1 data bit transmitted per UI; 1 UI = 0.5 clock
+  * cycles), the PLL clock may be 2, 4, 6, 8, 12, or 16 GHz. With a serializer
+  * ratio of 16, this results in a 0.125-1 GHz AFE digital clock.
+  *
+  * @groupname data Data signals
+  * @groupprio data 50
+  * @groupname impedance Impedance control signals
+  * @groupprio impedance 100
+  * @groupname phase Phase control signals
+  * @groupprio phase 101
+  * @groupname receiver Receiver control signals
+  * @groupprio receiver 102
+  * @groupname freq Frequency control signals
+  * @groupprio freq 103
+  * @groupname clock Clock control signals
+  * @groupprio clock 104
+  */
 class MainbandAfeIo(
     lanes: Int = 16,
     serializerRatio: Int = 16,
 ) extends Bundle {
-  // Data to transmit on the mainband.
-  // Output from the async FIFO.
+
+  /** Data to transmit on the mainband.
+    *
+    * Output from the async FIFO.
+    *
+    * @group data
+    */
   val txData = Decoupled(Vec(lanes, Bits(serializerRatio.W)))
 
-  // Data received on the mainband.
-  // Input to the async FIFO.
+  /** Data received on the mainband.
+    *
+    * Input to the async FIFO.
+    *
+    * @group data
+    */
   val rxData = Flipped(Decoupled(Vec(lanes, Bits(serializerRatio.W))))
 
   /////////////////////
@@ -74,46 +116,83 @@ class MainbandAfeIo(
   // Setting txZpu = txZpd = 0 sets drivers to hi-z.
   /////////////////////
 
-  // TX pull up impedance control.
+  /** TX pull up impedance control.
+    *
+    * @group impedance
+    */
   val txZpu = Output(Vec(lanes, UInt(4.W)))
-  // TX pull down impedance control.
+
+  /** TX pull down impedance control.
+    *
+    * @group impedance
+    */
   val txZpd = Output(Vec(lanes, UInt(4.W)))
-  // RX impedance control.
+
+  /** RX impedance control.
+    *
+    * @group impedance
+    */
   val rxZ = Output(Vec(lanes, UInt(4.W)))
 
   /////////////////////
   // phase control
   /////////////////////
 
-  // Global (per-module) phase control.
+  /** Global (per-module) phase control.
+    *
+    * @group phase
+    */
   val txGlobalPhaseSel = Output(UInt(4.W))
-  // Per-lane phase control.
+
+  /** Per-lane phase control.
+    *
+    * @group phase
+    */
   val txLaneDeskew = Output(Vec(lanes, UInt(4.W)))
-  // Per-lane phase control.
+
+  /** Per-lane phase control.
+    *
+    * @group phase
+    */
   val rxLaneDeskew = Output(Vec(lanes, UInt(4.W)))
 
   /////////////////////
   // frequency control
   /////////////////////
+  /** @group freq */
   val txFreqSel = Output(UInt(4.W))
 
   /////////////////////
   // receiver control
   /////////////////////
-  // Mainband receiver enable.
+  /** Mainband receiver enable.
+    *
+    * @group receiver
+    */
   val rxEn = Output(Bool())
-  // Per-lane vref/offset cancellation control.
+
+  /** Per-lane vref/offset cancellation control.
+    *
+    * @group receiver
+    */
   val rxVref = Output(Vec(lanes, UInt(4.W)))
 
   /////////////////////
   // clock control
   /////////////////////
-  // Clock gating control.
+  /** Clock gating control.
+    *
+    * @group clock
+    */
   val txClockEn = Output(Bool())
-  // Clock parking level.
-  //
-  // Per the UCIe spec, must alternate between high and low
-  // on subsequent clock gating events. If the link is using
-  // free running clock mode, this signal has no effect.
+
+  /** Clock parking level.
+    *
+    * Per the UCIe spec, must alternate between high and low on subsequent clock
+    * gating events. If the link is using free running clock mode, this signal
+    * has no effect.
+    *
+    * @group clock
+    */
   val txClockPark = Output(Bool())
 }

src/main/scala/Decoupled3.scala

@@ -2,6 +2,18 @@ package edu.berkeley.cs.ucie.digital
 
 import chisel3._
 
+/** An I/O Bundle containing `valid`, `ready`, and `irdy` signals that handshake
+  * the transfer of data stored in the 'bits' subfield.
+  *
+  * The base protocol implied by the directionality is that the producer uses
+  * the interface as-is (outputs bits) while the consumer uses the flipped
+  * interface (inputs bits). The actual semantics of ready/valid are enforced
+  * via the use of concrete subclasses.
+  * @param gen
+  *   the type of data to be wrapped in Ready/Valid
+  * @groupdesc Signals
+  *   The actual hardware fields of the Bundle
+  */
 abstract class ReadyValid3IO[+T <: Data](gen: T) extends Bundle {
 
   /** Indicates that the consumer is ready to accept the data this cycle

src/main/scala/Rdi.scala

@@ -3,46 +3,59 @@ package edu.berkeley.cs.ucie.digital
 import chisel3._
 import chisel3.util._
 
-// The raw D2D interface (RDI), from the perspective of the D2D Adapter.
+/** The raw D2D interface (RDI), from the perspective of the D2D Adapter. */
 class Rdi(width: Int, sbWidth: Int) extends Bundle {
-  // Adapter to Physical Layer data.
-  // Encompasses lp_irdy, lp_valid, and pl_trdy from the UCIe specification.
+
+  /** Adapter to Physical Layer data.
+    *
+    * Encompasses lp_irdy, lp_valid, and pl_trdy from the UCIe specification.
+    */
   val lpData = Decoupled3(Vec(width, UInt(8.W)))
 
-  // Physical Layer to Adapter data.
-  // Encompasses pl_valid and pl_data from the UCIe specification.
-  // Note that backpressure is not possible.
-  // Data should be sampled whenever valid is asserted at a clock edge.
+  /** Physical Layer to Adapter data.
+    *
+    * Encompasses `pl_valid` and `pl_data` from the UCIe specification. Note
+    * that backpressure is not possible. Data should be sampled whenever valid
+    * is asserted at a clock edge.
+    */
   val plData = Flipped(Valid(Vec(width, UInt(8.W))))
 
-  // When asserted at a rising clock edge, it indicates a single credit return from the
-  // Adapter to the Physical Layer for the Retimer Receiver buffers. Each credit corresponds
-  // to 256B of mainband data. This signal must NOT assert for dies that are not UCIe
-  // Retimers.
+  /** When asserted at a rising clock edge, it indicates a single credit return
+    * from the Adapter to the Physical Layer for the Retimer Receiver buffers.
+    * Each credit corresponds to 256B of mainband data. This signal must NOT
+    * assert for dies that are not UCIe Retimers.
+    */
   val lpRetimerCrd = Output(Bool())
 
-  // When asserted at a rising clock edge, it indicates a single credit return from the
-  // Retimer to the Adapter. Each credit corresponds to 256B of mainband data. This signal
-  // must NOT assert if the remote Link partner is not a Retimer.
+  /** When asserted at a rising clock edge, it indicates a single credit return
+    * from the Retimer to the Adapter. Each credit corresponds to 256B of
+    * mainband data. This signal must NOT assert if the remote Link partner is
+    * not a Retimer.
+    */
   val plRetimerCrd = Input(Bool())
 
-  // Adapter request to Physical Layer to request state change.
+  /** Adapter request to Physical Layer to request state change. */
   val lpStateReq = Output(PhyStateReq())
 
-  // Adapter to Physical Layer indication that an error has occurred which requires the Link
-  // to go down. Physical Layer must move to LinkError state and stay there as long as
-  // lp_linkerror=1. The reason for having this be an indication decoupled from regular
-  // state transitions is to allow immediate action on part of the Adapter and Physical Layer
-  // in order to provide the quickest path for error containment when applicable (for
-  // example, a viral error escalation must map to the LinkError state).
-  // The Adapter must OR internal error conditions with lp_linkerror received from
-  // Protocol Layer on FDI.
+  /** Adapter to Physical Layer indication that an error has occurred which
+    * requires the Link to go down. Physical Layer must move to LinkError state
+    * and stay there as long as lp_linkerror=1. The reason for having this be an
+    * indication decoupled from regular state transitions is to allow immediate
+    * action on part of the Adapter and Physical Layer in order to provide the
+    * quickest path for error containment when applicable (for example, a viral
+    * error escalation must map to the LinkError state). The Adapter must OR
+    * internal error conditions with lp_linkerror received from Protocol Layer
+    * on FDI.
+    */
   val lpLinkError = Output(PhyStateReq())
 
-  // Physical Layer to Adapter Status indication of the Interface.
-  // The status signal is permitted to transition from Physical Layer autonomously when
-  // applicable. For example the Physical Layer asserts the Retrain status when it decides to
-  // enter retraining either autonomously or when requested by remote agent.
+  /** Physical Layer to Adapter Status indication of the Interface.
+    *
+    * The status signal is permitted to transition from Physical Layer
+    * autonomously when applicable. For example the Physical Layer asserts the
+    * Retrain status when it decides to enter retraining either autonomously or
+    * when requested by remote agent.
+    */
   val plStateStatus = Input(PhyState())
 
   val plInbandPres = Input(Bool())