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>
<section> <section>
<h2>Introduction</h2> <h2>Undocumented Hardware = Bad</h2>
<h4 class="fragment">(But so easy to do!)</h4>
<aside class="notes"> <aside class="notes">
This is the Open ISA miniconf, which today tends to mean FPGAs. This means that Undocumented hardware is bad. There are all sorts of quirks, and even if you have
hardware and software are both extensible, and developers will be able to extend the source code, it can be very difficult to read. I'm the primary developer for
the hardware in addition to making modifications to your software package. 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> </aside>
</section> </section>
@ -122,19 +130,24 @@
</section> </section>
<section> <section>
<h2>Undocumented Hardware = Bad</h2> <h2>Enterprise Documentation</h2>
<h4>(But so easy to do!)</h4> <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"> <aside class="notes">
Undocumented hardware is bad. There are all sorts of quirks, and even if you have Most enterprise documentation is written by a team of writers using Microsoft Word.
the source code, it can be very difficult to read. I'm the primary developer for We're open source developers, and we prefer to use our own tools such as Git and CI
the Fomu project, and this talk will cover some of the issues I've run into with to create documentation for us. Because we're lazy. And prone to making mistakes.
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> </aside>
</section> </section>
@ -385,6 +398,23 @@ dq.o.eq(
<section> <section>
<h2>SVD: Documentation for Machines</h2> <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"> <aside class="notes">
Having documentation for humans is great, but we can go one step further and 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 make documentation for computers. SVD is an XML format defined by ARM that
@ -420,8 +450,16 @@ dq.o.eq(
<section> <section>
<h2>Renode: Fancy Register Logging</h2> <h2>Renode: Fancy Register Logging</h2>
<img data-src="img/renode-debug.png"> <table width="100%">
<img data-src="img/renode-ui.png"> <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"> <aside class="notes">
We can also import this SVD file into an emulator such as Renode, which will 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 print out fields and flags that get accessed, giving us greater visibility into
@ -431,6 +469,13 @@ dq.o.eq(
<section> <section>
<h2>Benefits of Higher Level Languages</h2> <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"> <aside class="notes">
By using a higher level language, we are able to describe the hardware 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 in greater detail than if we used Verilog or VHDL. We can add additional
@ -441,8 +486,8 @@ dq.o.eq(
</section> </section>
<section> <section>
<h2>Documentation helps you</h2>
<h2>Documentation helps others</h2> <h2>Documentation helps others</h2>
<h2 class="fragment">Documentation helps you</h2>
<aside class="notes"> <aside class="notes">
Documenting your hardware is important because it is necessary for you to 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 write software that interfaces with it today, and it helps you work with