xobs/lca2020-pay-it-forward
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

index: first release candidate

Browse Source 
Signed-off-by: Sean Cross <sean@xobs.io>
This commit is contained in:
Sean Cross 2020-01-03 10:58:11 +08:00
parent f7c304048b
commit 7323704130
1 changed files with 64 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
index.html
View File

@ -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