From f1ad5b58e8a749d558758288d03ce75bf6b8ff9c Mon Sep 17 00:00:00 2001
From: Megan Wachs
Date: Thu, 18 Mar 2021 16:47:58 -0700
Subject: Reorganize website docs (#1806)

Updates to chisel3 documentation for website:
* guard code examples with mdoc and fix errors encountered along the way
* move some website content here vs splitting the content across two repos
* Bring in the interval-types and loading memories content so that it will be visible from the website
* remove all references to the wiki (deprecated)
* Remove reference to Wiki from the README
* fix tabbing and compile of chisel3-vs-chisel2 section
* Appendix: faqs now guarded and compile
* FAQs: move to resources section---
 docs/src/explanations/combinational-circuits.md | 84 +++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 docs/src/explanations/combinational-circuits.md

(limited to 'docs/src/explanations/combinational-circuits.md')

diff --git a/docs/src/explanations/combinational-circuits.md b/docs/src/explanations/combinational-circuits.md
new file mode 100644
index 00000000..b9e5b8c6
--- /dev/null
+++ b/docs/src/explanations/combinational-circuits.md
@@ -0,0 +1,84 @@
+---
+layout: docs
+title:  "Combinational Circuits"
+section: "chisel3"
+---
+
+# Combinational Circuits
+
+A circuit is represented as a graph of nodes in Chisel.  Each node is
+a hardware operator that has zero or more inputs and that drives one
+output.  A literal, introduced above, is a degenerate kind of node
+that has no inputs and drives a constant value on its output.  One way
+to create and wire together nodes is using textual expressions.  For
+example, we can express a simple combinational logic circuit
+using the following expression:
+
+```scala
+(a & b) | (~c & d)
+```
+
+The syntax should look familiar, with `&` and `|`
+representing bitwise-AND and -OR respectively, and `~`
+representing bitwise-NOT.  The names `a` through `d`
+represent named wires of some (unspecified) width.
+
+Any simple expression can be converted directly into a circuit tree,
+with named wires at the leaves and operators forming the internal
+nodes.  The final circuit output of the expression is taken from the
+operator at the root of the tree, in this example, the bitwise-OR.
+
+Simple expressions can build circuits in the shape of trees, but to
+construct circuits in the shape of arbitrary directed acyclic graphs
+(DAGs), we need to describe fan-out.  In Chisel, we do this by naming
+a wire that holds a subexpression that we can then reference multiple
+times in subsequent expressions.  We name a wire in Chisel by
+declaring a variable.  For example, consider the select expression,
+which is used twice in the following multiplexer description:
+```scala
+val sel = a | b
+val out = (sel & in1) | (~sel & in0)
+```
+
+The keyword `val` is part of Scala, and is used to name variables
+that have values that won't change.  It is used here to name the
+Chisel wire, `sel`, holding the output of the first bitwise-OR
+operator so that the output can be used multiple times in the second
+expression.
+
+### Wires
+
+Chisel also supports wires as hardware nodes to which one can assign values or connect other nodes.
+
+```scala
+val myNode = Wire(UInt(8.W))
+when (isReady) {
+  myNode := 255.U
+} .otherwise {
+  myNode := 0.U
+}
+```
+
+```scala
+val myNode = Wire(UInt(8.W))
+when (input > 128.U) {
+  myNode := 255.U
+} .elsewhen (input > 64.U) {
+  myNode := 1.U
+} .otherwise {
+  myNode := 0.U
+}
+```
+
+Note that the last connection to a Wire takes effect. For example, the following two Chisel circuits are equivalent:
+
+```scala
+val myNode = Wire(UInt(8.W))
+myNode := 10.U
+myNode := 0.U
+```
+
+```scala
+val myNode = Wire(UInt(8.W))
+myNode := 0.U
+```
-- 
cgit v1.2.3