[core] Add the "period" field, docs to ClockDomain

Add a "period" field to the ClockDomain.  Note: the fields of this
domain (or any upstream domain) are highly experimental and may change at
any time.

Additionally, add some documentation about what a ClockDomain is.

Signed-off-by: Schuyler Eldridge <[email protected]>

Author: seldridge

core/src/main/scala/chisel3/domains/ClockDomain.scala

@@ -5,10 +5,18 @@ package chisel3.domains
 import chisel3.domain.{Domain, Field}
 import chisel3.experimental.UnlocatableSourceInfo
 
+/** A Clock Domain
+  *
+  * This represents a collection of signals that toggle together.  This does not
+  * necessarily mean that signals associated with this domain share a clock or
+  * will toggle in a predictable way.  I.e., this domain can be used to describe
+  * asynchronous signals or static signals (like strap pins).
+  */
 object ClockDomain extends Domain()(sourceInfo = UnlocatableSourceInfo) {
 
   override def fields: Seq[(String, Field.Type)] = Seq(
-    "name" -> Field.String
+    "name" -> Field.String,
+    "period" -> Field.Integer
   )
 
 }

src/test/scala-2/chiselTests/DomainSpec.scala

@@ -43,6 +43,7 @@ class DomainSpec extends AnyFlatSpec with Matchers with FileCheck {
       """|CHECK:      circuit Foo :
          |CHECK:        domain ClockDomain :
          |CHECK-NEXT:     name : String
+         |CHECK-NEXT:     period : Integer
          |
          |CHECK:        domain PowerDomain :
          |CHECK-NEXT:     name : String