Most of the microprocessors I've worked with have had fairly decent manuals. They're well organized and clear for the most part. It's not terribly engrossing reading, of course, but they get the job done. I recently had to do some development for an Altera FPGA, so I was designing hardware logic instead of embedded software programs, and the experience with the documentation was entirely different.
Altera has mountains of documentation on their products and development environment. Their flagship Quartus II software alone has a three-volume PDF manual that totals nearly 2,500 pages. They have dozens of other manuals covering their NIOS embedded processor, Qsys system builder, and the host of other products and software they provide for developing on FPGAs. That doesn't even account for the FPGA-specific documentation they have. On top of all of this documentation, they have oodles of online training courses because now that they have this massive edifice of documentation, no one wants to read it.
You would think with this amount of documentation, I would be able to find anything I needed to for completing my design. Maybe it wouldn't be easy or fast to find it, but the information should exist somewhere in all of that material. I'm not so sure that it does.
So what did I need to know for my design? It was a very simple design for a MAX II CPLD, one of Altera's smaller devices. The design ended up being a scant 65 lines of Verilog code, including blank lines and a couple comments. I've done plenty of hardware design before, so this should not have been difficult, but I needed to know three basic things that were specific to this Altera device to get my design working.
- I needed to know how to get a clock into the design because I needed to use a few 16-bit registers that require a clock.
- Additionally, those registers needed to be reset at power-on so that they would be in a known state.
- I needed to know how to connect all of the I/O signals to physical device pins.
I poured over the documentation trying to find information on any of these issues using a Verilog-only design flow. I went through half a dozen training courses looking for anything that might help. These three things - clock, reset, and I/O pins - are basic requirements that any design would need, and I couldn't find anything about them for a pure Verilog design flow.
Most examples used Verilog files lower down in the design hierarchy with schematics at the top. The few that used only Verilog showed how to make a comparator or a multiplier - pure combinational logic with no clock and no reset. And of course they didn't show how to connect the module signals to I/O pins. From all of the tutorials, examples, and documentation I went through, it looked like I was going to have to jump through development environment hoops to synthesize a 65-line Verilog design. I was disappointed.
I decided to turn to Google and see what I could dig up. I tried "verilog only design in quartus," and to my dismay, the first four hits were for Altera documentation that I had already looked through! What is the deal here? But the fifth link was the jackpot. A professor at Swathmore College, a college I've never heard of, put up a most helpful one-page tutorial on how to do a Verilog-only design in Quartus. The last part of the tutorial even had a clock!
The tutorial didn't have everything I needed, but it covered the biggest sticking point - how to connect the module pins to physical I/O pins. That got me on my way, and I was able to resolve the clock and reset issues through some experimentation. I ended up having to drive a global reset signal from a GPIO pin on an attached microprocessor because the MAX II device does not actually have an internally generated power-on-reset. That wasn't as clean as I would have liked, but it worked.
In the end I wasted a couple days floundering around in the Altera documentation and training materials trying to solve some basic design issues that should have been dead simple. Would it kill Altera to make a short training course with a Verilog-only design example, and include a clock and reset in it?! Or maybe they could write up a quick start guide for a non-trivial Verilog-only design.
The issues I struggled with are fundamental to any design, and Verilog continues to gain in popularity for hardware design because of its many advantages over schematic capture, including my personal favorite: the ability to use version control because it's all text files. Not all designs need the enormous complexity that comes with Altera's more involved design flows. Not everyone needs to know all of the minute details of timing analysis, clock insertion delays, synthesis constraints, and floor planning. I would venture to say that most designs don't need these things, at least at first, but designers would greatly benefit from a simple, straightforward tutorial that would get them up and running with a Verilog design flow quickly. Altera is dropping the ball here.
Don't make the same mistakes that Altera is making. If you're creating documentation for a product that requires a fair amount of configuration, design and implementation, think about the basic steps that first-time customers would need to take to get up and running with your product quickly. Try to forget everything you know about the details of your product and imagine what it would be like coming at it with no prior knowledge of how to set it up. Things that seem obvious to you will be confusing to new customers, even if they are otherwise experienced designers or developers.
You don't have to assume you know nothing about the domain, but pretend you've never been exposed to this particular product before. How do you make it do something useful in twenty minutes or less that you could build on later? Lots of products are doing this kind of quick-start stuff today. All of the tutorials and screencasts for Ruby on Rails come immediately to mind. If you can get your customers over that initial roadblock and help them create something useful right away, they will greatly appreciate the extra thought you've put into making their lives easier.
No comments:
Post a Comment