From 4149157df6531d124483d992daf96cf4e62a0f0c Mon Sep 17 00:00:00 2001
From: mergify[bot]
Date: Fri, 4 Nov 2022 18:20:07 +0000
Subject: Add PartialDataView.supertype (backport #2826) (#2827)

* Add PartialDataView.supertype (#2826)

This factory method makes it easy to create PartialDataViews from a
Bundle type to its supertype. Because of the typing relationship, there
is no need to provide a mapping between fields. The only thing necessary
is to provide a function for constructing an instance of the supertype
from an instance of the subtype.

(cherry picked from commit 251d454a224e5a961438ba0ea41134d7da7a5992)

# Conflicts:
#	core/src/main/scala/chisel3/experimental/dataview/package.scala
#	src/test/scala/chiselTests/experimental/DataView.scala

* Resolve backport conflicts

Co-authored-by: Jack Koenig <koenig@sifive.com>---
 docs/src/cookbooks/dataview.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

(limited to 'docs/src/cookbooks')

diff --git a/docs/src/cookbooks/dataview.md b/docs/src/cookbooks/dataview.md
index ed969ca1..f970cfe4 100644
--- a/docs/src/cookbooks/dataview.md
+++ b/docs/src/cookbooks/dataview.md
@@ -12,6 +12,7 @@ section: "chisel3"
 * [How do I connect a subset of Bundle fields?](#how-do-i-connect-a-subset-of-bundle-fields)
     * [How do I view a Bundle as a parent type (superclass)?](#how-do-i-view-a-bundle-as-a-parent-type-superclass)
     * [How do I view a Bundle as a parent type when the parent type is abstract (like a trait)?](#how-do-i-view-a-bundle-as-a-parent-type-when-the-parent-type-is-abstract-like-a-trait)
+    * [How can I use `.viewAs` instead of `.viewAsSupertype(type)`?](#how-can-i-use-viewas-instead-of-viewassupertypetype)
 
 ## How do I view a Data as a UInt or vice versa?
 
@@ -177,3 +178,37 @@ As indicated in the comment, abstract methods must still be implemented.
 This is the same that happens when one writes `new Bundle {}`,
 the curly braces create a new concrete subclass; however, because `Bundle` has no abstract methods,
 the contents of the body can be empty.
+
+### How can I use `.viewAs` instead of `.viewAsSupertype(type)`?
+
+While `viewAsSupertype` is helpful for one-off casts, the need to provide a type template object
+each time can be onerous.
+Because of the subtyping relationship, you can use `PartialDataView.supertype` to create a
+`DataView` from a Bundle type to a parent type by just providing the function to construct an
+instance of the parent type from an instance of the child type.
+The mapping of corresponding fields is automatically determined by Chisel to be the fields defined
+in the supertype.
+
+```scala mdoc:silent:reset
+import chisel3._
+import chisel3.experimental.dataview._
+
+class Foo(x: Int) extends Bundle {
+  val foo = UInt(x.W)
+}
+class Bar(val x: Int) extends Foo(x) {
+  val bar = UInt(x.W)
+}
+// Define a DataView without having to specify the mapping!
+implicit val view = PartialDataView.supertype[Bar, Foo](b => new Foo(b.x))
+
+class MyModule extends Module {
+  val foo = IO(Input(new Foo(8)))
+  val bar = IO(Output(new Bar(8)))
+  bar.viewAs[Foo] := foo // bar.foo := foo.foo
+  bar.bar := 123.U       // all fields need to be connected
+}
+```
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new MyModule)
+```
-- 
cgit v1.2.3