Writing Tutorials Sucks Donkeys

Posted by: Dave Vandenbout 6 years, 5 months ago


I'm writing a new book about doing FPGA design using Xilinx ISE WebPACK and the XuLA board. I've reproduced the preface for the book below. Here are the important points:

  • I'm currently writing the book. New chapters will be released as I write them. There are currently four chapters available that cover FPGA basics, ISE compiler flow basics, entering VHDL, synthesizing, simulating, implementing, downloading and running a simple LED blinker design. Additional planned topics are listed in the preface.
  • The book is covered under a Creative Commons Attribution-Sharealike 3.0 Unported license and stored on Github. So anyone can grab it, modify it, sell it, or whatever as long as they leave the other author names and affiliations intact and offer it freely with the same rights they got.
  • I'm using FOSS tools like LibreOffice/OpenOffice and Inkscape for creating the text, so nobody will have to buy any tools if they want to modify it.


There are numerous requests in Internet forums that go something like this:

"I am new to using FPGAs. What are they? How do I start? Is there a tutorial and some cheap/free tools I can use to learn more?"

The short answer is “Yes”.

The long answer is this book. It will briefly describe FPGAs and then show you how to apply them to your problems using a low-cost board and some free software. My discussion will be oriented towards using Xilinx FPGAs, but most of what I'll say is applicable to other brands of FPGAs.

But first, a little history...

Writing Tutorials Sucks Donkeys!

Yeah, I mean it and I have the experience to back it up.

I've written a lot of documentation over the past twenty years. It's in the nature of my business. I need to write manuals and application notes for my FPGA board customers. I need to generate content for my web pages. I need to write documentation for myself just so I can remember what I've done and where I left off.

But the documentation I hate writing most of all is tutorials. With a tutorial, you can't assume your reader knows much of anything. You have to build from the ground up. That requires a lot of text, figures, pictures, design examples, etc. And you have to polish and proofread it more thoroughly to make sure its meaning is clear because, if it isn't, someone is going to read it the wrong way and give you a bunch of static about it.

Allow me to take you on a trip down Memory Lane and recount some of the tutorials I've written:

FPGA Workout - 236 pages: I wrote this book back in 1994. It showed how to build electronics using the Intel FLEXlogic FPGAs. (You didn't know Intel built FPGAs? Seems that nobody else did either - they exited the FPGA business around 1995.) I self-published this and had 2000 of them printed. I sold 1500, gave 300 away (one to every EE department in the USA), and watched the last 200 get ground under a bulldozer's tracks in the Wake County landfill (I just couldn't stand having them around anymore).

The Practical Xilinx Designer Lab Book - 300 pages: I wrote this for Prentice Hall back in 1997. They were publishing a student package in cooperation with Xilinx that included this book along with the Foundation FPGA design software. It was a good product at the time. My book covered how to build electronics using Xilinx FPGAs. It was a real bear working with Prentice Hall after self-publishing my first book. I created and proofread all the text and figures, then Prentice Hall re-entered all that material using Framemaker and I had to proofread it all again to catch any transcription errors. (To their credit, there weren't very many. Then again, I wasn't looking that hard.)

myCSoC - 213 pages: I wrote this e-book back in 2000. It discussed how to construct electronic systems around the Triscend TE505 chip. (The TE505 combined an 8051 microcontroller with an FPGA on a single chip.) I distributed this book as PDFs from my website and used it as a sales tool for the myCSoC Kit . That came to an end when Triscend went out of business around 2003 and Xilinx gobbled up their dessicated remains. (I still have five-hundred unused TE505 chips from that venture. Anybody want them? Anybody?)

The Practical Xilinx Designer Lab Book Version 1.5 - 450 pages: It wasn't enough to do this once; I went ahead and did a revision! And I added an extra 150 pages of material on - can you guess? - designing electronics using FPGAs. I tried to make a deal with Prentice Hall wherein I would write the print revision for free, and they would grant me the electronic rights to distribute it on the web. This was 1999 and they just couldn't get their heads around this, but they knew they wanted no part of it. Instead, they just paid me $15,000 for the re-write and told me to drop all the crazy talk. After the book was written, they packaged it with some CDROMs which - instead of containing the Xilinx software - contained test data for an anesthesiology text book! Yeesh, the customer support calls I got! Looking back on it, I realized that all the whipped cream in the world would never make this turd taste any better.

Pragmatic Logic Design With Xilinx Foundation 2.1i - 394 pages: This was what I originally wanted to do for Prentice Hall. An online book with a separate PDF for each chapter. Plenty of room to add as much text and as many figures as were needed because it didn't have to fit into a fixed amount of paper. Easily edited and changed to correct any errors that were found. I got five chapters of this text finished. Then Xilinx released a version of their free WebPACK tools that targeted FPGAs (instead of just CPLDs) and the market for the not-free Foundation software vanished. So did any incentive I had to finish this book.

Introduction to WebPACK X.Y - from 78 pages up to 130 pages: I wrote this tutorial to show how to use the free Xilinx ISE WebPACK software, which had a markedly different user interface than the Foundation software. I wrote a version of the tutorial for WebPACK 1.5 and then 3.1 (these only supported Xilinx CPLDs), then two re-writes for 4.1 (one for CPLDs and another for FPGAs), another re-write for 5.2 (FPGAs only, this time), two re-writes for 6.1 (one targeting the XSA-100 board, and another for the XSB-300E board), one more minor re-write for 6.3 (because of the introduction of the new XSA-3S1000 board), another re-write for 8.1, and a final re-write for ISE WebPACK 10. Xilinx is up to ISE 13 now and, thankfully, it still operates pretty much the same as version 10 because I haven't had the energy to re-write the tutorial. It still serves as a pretty good introduction to the Xilinx software.

All told, that's over two-thousand pages of tutorials. That's a lot, regardless of whether it's mostly roses or shit. What I hated most about doing the tutorials was the boring sameness of it. Each looks like a rehash of the previous one. So I cringe when I think about writing another (hence my three year hiatus from re-doing the WebPACK tutorial).

Here I Go Again

But it looks like I am writing another one. The XuLA board needs a tutorial; it's just too different from any of my other boards and the people who might use it probably have no experience with FPGAs. So they need something to help them get started. But, in order to get me started, I'm going to write this tutorial a bit differently so it won't be so boring. Here are the guidelines I set for myself:

I won't re-invent the wheel. There's no reason to re-write everything about digital logic design just so I can introduce you to FPGAs – the web is full of good information. I'll add links to good stuff I find to cut my workload and to produce a better text in less time.

I won't fence it in. What I really mean is: steal this book!. I'm placing the source directory for it on Github. You can copy it, modify it, sell it - I don't care. I want you to do this! Please take it, add your own stuff and make it better. All I ask is that you respect the terms of the Creative Commons license I applied to this work. Basically, that means don't remove the names/affiliations of anyone else who worked on this, and provide others with the same rights to it that you got. (But check the actual license to get the fine points.)

I won't let others fence it in. I'm using FOSS like LibreOffice and Inkscape to write this book. That removes some barriers for anyone who wants to work on it because they won't have to pay for the tools. And it keeps the source files in non-proprietary formats.

I won't be a prisoner of perfection. I've often held onto things too long before releasing them, trying to remove every error I can find. That's not the case with this book – you'll find spelling and grammar errors, subject/verb disagreements, inconsistent formatting, hand-drawn figures and lots of other stuff. But this won't matter to someone who really needs the material. (For those who do care about the finer points, you can tell me what errors you find and I'll get around to fixing them, or you can get the source and fix them for me.)

I'll use the right medium for the right message. Text and figures are great for a tutorial so you can read along while you actually do it. Screencasts and videos are almost always more difficult to follow, especially all the diddling-about with typing text and clicking icons that goes on with FPGA design tools. But there is a place for these, particularly when demonstrating the actual operation of some circuitry.

What This Is and Is Not

This book discusses how to use the Xilinx ISE WebPACK software to build FPGA designs for the XuLA FPGA board. Along the way, you'll see:

  • How to start an FPGA project.

  • How to target a design to a particular type of FPGA.

  • How to describe a logic circuit using VHDL and/or schematics.

  • How to detect and fix VHDL syntactical errors.

  • How to synthesize a netlist from a circuit description.

  • How to simulate a circuit.

  • How to implement the netlist for an FPGA.

  • How to check device utilization and timing for an FPGA.

  • How to generate a bitstream for an FPGA.

  • How to download a bitstream into an FPGA.

  • How to test the programmed FPGA.

  • How to detect and fix errors.

I'll also delve into things like:

  • How to build hierarchical designs.

  • How to build state machines.

  • How to build mixed-mode designs using VHDL, Verilog and schematics.

  • How to use Digital Clock Managers.

  • How to use block RAMs.

  • How to use multipliers.

  • How to use IP and soft cores.

  • How to use external components like SDRAM, VGA, audio, ADC, DAC.

That said, here are some of the things this book will not teach you (I may be wrong here; this book isn't even written yet, plus who knows what others may add):

  • It will not teach you how to use VHDL. There are plenty of good VHDL textbooks already.

  • It will not teach you how to choose the best type of FPGA for your particular design. I'm oriented toward using the FPGA on the XuLA board.

  • It will not show you every feature of the ISE software and discuss how to set every option and property. This software already has a good help system and extensive manuals, so those should suffice.

In short, this book will get you started using the XILINX ISE software for doing FPGA designs with the XuLA board. After you finish, you should be able to move on to more advanced topics.


Currently unrated


  • There are currently no comments

New Comment

required (not published)

Recent Posts






RSS / Atom