From 7323704130f0766472cc67abb30f9a47aaa12b8f Mon Sep 17 00:00:00 2001
From: Sean Cross <sean@xobs.io>
Date: Fri, 3 Jan 2020 10:58:11 +0800
Subject: [PATCH] index: first release candidate

Signed-off-by: Sean Cross <sean@xobs.io>
---
 index.html | 83 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 64 insertions(+), 19 deletions(-)

diff --git a/index.html b/index.html
index bac5fb5..82dd66c 100644
--- a/index.html
+++ b/index.html
@@ -94,11 +94,19 @@
             </section>
 
             <section>
-                <h2>Introduction</h2>
+                <h2>Undocumented Hardware = Bad</h2>
+                <h4 class="fragment">(But so easy to do!)</h4>
                 <aside class="notes">
-                    This is the Open ISA miniconf, which today tends to mean FPGAs.  This means that
-                    hardware and software are both extensible, and developers will be able to extend
-                    the hardware in addition to making modifications to your software package.
+                    Undocumented hardware is bad.  There are all sorts of quirks, and even if you have
+                    the source code, it can be very difficult to read.  I'm the primary developer for
+                    the Fomu project, and this talk will cover some of the issues I've run into with
+                    respect to documentation.  It is most directly related to the LiteX and Migen
+                    projects, but the concepts will carry over into any other Hardware Description
+                    Language you may use.
+
+                    The goal of this talk is to show how it's easy to document hardware with
+                    the right framework, and how it's easier to have a project that's documented
+                    than one that isn't.
                 </aside>
             </section>
 
@@ -122,19 +130,24 @@
             </section>
 
             <section>
-                <h2>Undocumented Hardware = Bad</h2>
-                <h4>(But so easy to do!)</h4>
+                <h2>Enterprise Documentation</h2>
+                <table>
+                    <tr>
+                        <td>
+                            <img height="400" class="fragment" data-src="img/Microsoft_Office_Word.svg" type="image/svg+xml"/>
+                        </td>
+                        <td width="50%">
+                            <div class="fragment">
+                                <img data-src="img/Git-logo.svg" type="image/svg+xml"/>
+                                <img data-src="img/Travis_CI_Logo.svg" type="img/svg+xml"/>
+                            </div>
+                        </td>
+                    </tr>
+                </table>
                 <aside class="notes">
-                    Undocumented hardware is bad.  There are all sorts of quirks, and even if you have
-                    the source code, it can be very difficult to read.  I'm the primary developer for
-                    the Fomu project, and this talk will cover some of the issues I've run into with
-                    respect to documentation.  It is most directly related to the LiteX and Migen
-                    projects, but the concepts will carry over into any other Hardware Description
-                    Language you may use.
-
-                    The goal of this talk is to show how it's easy to document hardware with
-                    the right framework, and how it's easier to have a project that's documented
-                    than one that isn't.
+                    Most enterprise documentation is written by a team of writers using Microsoft Word.
+                    We're open source developers, and we prefer to use our own tools such as Git and CI
+                    to create documentation for us.  Because we're lazy.  And prone to making mistakes.
                 </aside>
             </section>
 
@@ -385,6 +398,23 @@ dq.o.eq(
 
             <section>
                 <h2>SVD: Documentation for Machines</h2>
+                <table>
+                    <tr>
+                        <td>
+                            <ul>
+                                <li>XML description file</li>
+                                <li>Interrupt numbers</li>
+                                <li>Memory layout</li>
+                                <li>Register definitions</li>
+                                <li>Register fields</li>
+                            </ul>
+                        </td>
+                        <td>
+                            <img data-src="img/CMSIS_SVD_Schema_Gen.png">
+                            <br/><small>Source: keil.com</small>
+                        </td>
+                    </tr>
+                </table>
                 <aside class="notes">
                     Having documentation for humans is great, but we can go one step further and
                     make documentation for computers.  SVD is an XML format defined by ARM that
@@ -420,8 +450,16 @@ dq.o.eq(
 
             <section>
                 <h2>Renode: Fancy Register Logging</h2>
-                <img data-src="img/renode-debug.png">
-                <img data-src="img/renode-ui.png">
+                <table width="100%">
+                    <tr>
+                        <td width="75%">
+                            <img data-src="img/renode-debug.png">
+                        </td>
+                        <td>
+                            <img data-src="img/renode-ui-tall.png">
+                        </td>
+                    </tr>
+                </table>
                 <aside class="notes">
                     We can also import this SVD file into an emulator such as Renode, which will
                     print out fields and flags that get accessed, giving us greater visibility into
@@ -431,6 +469,13 @@ dq.o.eq(
 
             <section>
                 <h2>Benefits of Higher Level Languages</h2>
+                <ul>
+                    <li>Greater code reuse</li>
+                    <li>More hardware description</li>
+                    <li>Better interoperability</li>
+                    <li>Automatic document generation</li>
+                    <li>Automatic SVD</li>
+                </ul>
                 <aside class="notes">
                     By using a higher level language, we are able to describe the hardware
                     in greater detail than if we used Verilog or VHDL.  We can add additional
@@ -441,8 +486,8 @@ dq.o.eq(
             </section>
 
             <section>
-                <h2>Documentation helps you</h2>
                 <h2>Documentation helps others</h2>
+                <h2 class="fragment">Documentation helps you</h2>
                 <aside class="notes">
                     Documenting your hardware is important because it is necessary for you to
                     write software that interfaces with it today, and it helps you work with