Proprietary CAD tools

CAD tools are freaking expensive (thousands of dollars per seat), and support is, to say the least, not always linear with the money paid. In fact, it is usually easier to obtain information about an open source tool than a proprietary CAD tool.

Recently, I had a python server script that consumed Gigs of RAM after it had run for about a week on a x86_64 machine. I searched the python website and discovered that there was a memory leak in the threading module. Upgrading to python 2.5.2 solved the problem.

Whenever I discover a problems with CAD tools, obtaining an answer from the support team is always an adventure. First they tell me to upgrade to the most recent, which is always impossible: nobody upgrades CAD tools when they attempt to tape out, you run with the version you have until the end. Second, they tell me they have never heard about the problem being reported. Thirdly, they want me to send them “the entire environment”. Yeah right, I will send millions of lines of our own proprietary code which you won’t be able to compile unless you have all the same versions of other tools like GNU Make, python, perl, and CAD tools from other companies! I usually end up working overtime to find out ways to work around the problem. All that for an expensive tool for which my employer pays support and maintenance fees!

I paid NOTHING for any open source tool I use, and I am able to know everything about them.

But the best support is truly from open source tools. Their bug databases are fully open, all their versions are documented with changelogs, and most have forums or mailing lists that can be searched openly. I can even ask questions on those mailing lists, and I usually get a response faster than for paid support! How can a group of unrelated people, working for different companies, or not working at all, with little or no VC money at all, create a better support structure for the software they write (and give it away for free), than companies that swim in cash?

It seems to me that companies with common needs (say for a synthesis tool or a verilog simulator) should band together and invest a small portion of their CAD budget in open source CAD tools. Eventually, it will pay back. I wonder what investors would think of that?

How to tape out ASICs like they’re software releases

ASICs are massive software projects. Millions of lines of design code, and millions of lines of QA code to make sure you are not taping out a coaster. Due to the high fabrication cost, ASICs tend to be released infrequently, as it makes economic sense to cram as many features as possible into a single release. The fabrication cost of providing N features is almost the same a providing N+M features, given the same geometry. So the more features you cram in there, the lower your cost per feature.

Except one thing: people. Past a certain size, the project is too big. It’s too big for people to fit all the features in their mind. Too many features to track at the same time, too many interactions between features, too many implications… the schedule slips. And slips again. And again. So the business decision is: tape out now, right now. And your answer is: we can’t, the HEAD of the database has all these features, under development, and at the same time we’re debugging them, and some files won’t even compile, we can’t tape out, we need to freeze the feature set, stabilize the code, run regressions for two months and bug fix as much as we can before we freeze RTL, then maybe fix a few dozen bugs in ECOs.

Everyone knows it sucks to do bug fixes in ECOs because it’s way harder than in RTL. It’s like bug fixing machine code, then porting the fix back to the source, without being allowed to run the compiler on the source code anymore!

But I digress, the question is, how should source code be managed to maintain it in a state where tape out opportunities are the norm rather than the exception? You obviously can’t allow chaotic commits to the source code database, much less chaotic commits to the release branch! Let’s examine those the source code management strategies used in software and try to see how they fit the ASIC development world.

The single branch broken trunk model: all the commits, design and verification, go to the same unique branch, stability is declared at certain points when enough simulations have managed to pass and designers happen to have been quiet on the feature front. Most times, the HEAD of the database is just broken.

This is possibly the easiest model to follow for people who cannot afford to learn how to use branches. However, the head being broken most of the time means that tape out dates are somewhat unpredictable as a period of stability, on an unknown committed feature set, is required for integration and bug fixes. This period of stability also impacts all future code development: since there is only one place for code to go, new development cannot be committed after RTL freeze.

In this model, the only way to allow new development after RTL freeze is to open a second database, and copy and paste all the code and the bug fixes over to the new database.

Pros: easy; no source code management learning curve
Cons: tape out dates are unpredictable; new code breaks working code all the time; continuing development after the RTL freeze is not possible

Broken trunk, tape out branch model
In this model, a branch is created in the database for each tape out tentative. Since it takes a few days to a few weeks before the code for tape out is known to be good for tape out, isolating tape out from the main development trunk is wise: development can continue and will not break the tape out code. Usually, only bug fixes are allowed on the tape out branch. A tape out branch can be abandoned when a better feature set is available on the trunk where a new tentative tape out branch can be created.

The ease with which these branches can be created and maintained heavily depends on the source code management software being used. CVS being one of the oldest SCM around is also the most primitive in terms of branch support. Support for branches is much more developed in git as repeated merges are supported, among other great features.

Pros: tape out and re-spins are isolated from development; back end team can control what goes into the tape out code without locking down the whole database
Cons: the development trunk is broken; a stability period is still required but it can be moved to the tape out branch while development continues on the trunk; back end engineers must learn how to use branches

Stable trunk, tape out branch model
In this model, developers are not allowed to commit directly to the trunk unless their code has passed some tests proving that it won’t have adverse effects on the rest of the code. The typical steps for this model are branch, edit, commit, test and merge. When the tests are successful, designers are allowed to merge the changes to the trunk. Changes to the tape out branches is done the same way.

Pros: the trunk is stable, tape out dates are more predictable as there is no stabilization period on the trunk; cowboy coders do not bring everyone down when they commit unstable code
Cons: stabilization happens on the branches, along with feature development; everyone must learn how to manage branches

It does not take long once you have branches in your methodology to realize that you want to merge to and from the stable trunk, since a feature branch may want to integrate a feature from the trunk which was not available at the time the branch was created. Fortunately, this kind of development is made easy by new decentralized source code management software such as git.

As a bonus, decentralized SCMs allow you to share code with others without releasing it to a central database, reducing the number of branches or tags visible to others.

Buildbot for ASIC regression?

A friend pointed me to Buildbot today. Every ASIC project I have worked on has more or less always required some form of automated system to insure new code did not break old code, and bugs were found on a continuous basis through regression testing.

The state space is so large in ASIC verification that running continuous regressions that apply random stimulus is necessary to find as many bugs as possible before releasing the code for fabrication. Usually, the person responsible for running those regressions and reporting the results to developers gets bored to death of this repetitive job and ends up building an entire system that runs these tests automatically.

Can Buildbot help in ASIC verification? The architecture of Buildbot appears to be the correct one, with a BuildMaster and a series of BuildSlaves.

However, after reading most of the documentation, it seems Buildbot is not directly usable for ASIC regression automation. This probably comes from the fact that software builds are not the same as ASIC builds.

A software build means compiling the code specifically for an architecture (x86, ia_64, etc), and running a set of tests, all on the same computer, to prove that the software can run flawlessly on a specific computer architecture.

An ASIC build means compiling the ASIC submodules and top level to executables, then run series of tests specific to those submodules and top level builds to find bugs in the ASIC. The underlying hardware architecture that is used to run those executables is irrelevant to the tests being run. The compiler that compiled the ASIC into executables must work on all the different computer architectures, but the resulting ASIC executables will behaves identically, regardless of the architecture on which they runs (x86, ia_64, etc).

This fundamental difference makes Buildbot unsuitable for ASIC verification unless some effort in made in customizing it. Specifically, I expect there would be customization required in the Builders. According to the control flow,

a Build is started on each of a set of configured Builders, all compiling/testing the same source code

and this leads me to believe that all tests that a Builder is configured to run will be farmed out to the same BuildSlave. There appears to be no load sharing for the tests once the main executable is build. There is probably a way to configure multiple Builders to share the load, but that would require manually balancing the tests on each Builder, taking the benefits of automation away.

Hopefully I am wrong and there is a way to load balance the tests, but until then, I think using Buildbot for ASIC verification is not a straightforward solution.

In any case, this show that constructing a system for regression automation is not a trivial problem that a script kiddie can do over a weekend.

irssi through an ssh tunnel

Using irssi on your local desktop to connect to an IRC server behind a firewall is easy using an ssh tunnel, providing you have ssh access through the firewall.

First open the ssh tunnel:

ssh -L 6667:irc_server:6667 user@remote.host.com


Then in another terminal on your local machine, type:

irssi -c localhost


irssi will connect to localhost on port 6667 – expecting to find an IRC server, ssh will redirect the localhost:6667 connection to irc_server:6667 through the ssh tunnel.

How one line of code quadruples testing – in hardware at least!

A sentence in an article by Joel Spolsky caught my attention: “Can’t we just default to IE7 mode? One line of code … Zip! Solved!”. This is the typical necessary solution that quadruples the testing effort. If you though it only doubled the testing, think again.

Let’s examine this in detail. First we have the code:

...
// When fizBoo is enabled, call it for additional sparkling
if (fizBooEnabled) {
  fizBoo();
}
...

All right, so how does this quadruple the testing? Well, first thing is that in hardware verification, there is no such thing as conditional compilation to remove FizBoo from the silicon: the fizBoo() function is always there. This is because only ONE chip is manufactured to supports all hardware architectures. In software, you can #ifdef things out of the executable based on architecture, but in hardware, everything is always there to support all of them. This way you can use the same hardware with a variety of operating systems (Windows, Linux) and a variety of architectures (Sun, IBM, low-end PCs, etc).

So now we have to test the fizBoo() in 4 different cases:

1. fizBooEnabled == 0, in systems where fizBoo() does not need to be called
2. fizBooEnabled == 1, in systems where fizBoo() adds some sparkling
3. fizBooEnabled == 0, in systems supporting fizBoo(), but if not called, only the additional sparkling is missing
4. fizBooEnabled == 1, in systems not supporting fizBoo(), to ensure there is no evil things like memory corruption or a bus error

One line of code quadruples testing. But this example is easy. It’s easy for the designer to put it in, easy for the tester to spot, and easy to cover off in a unit test.

But there are thousands of features in hardware, and end users are chaotic: they will plug in the hardware in the wrong architecture, and will load the wrong driver in the right architecture. The last thing they want though is the system to go up in flames. The hardware is expected to neither electrocute the user, nor cause memory corruption, regardless of how chaotic the end user is. End users are not the only chaotic people: your own software team is chaotic, even the team writing the driver for the hardware is chaotic!

In my opinion, this makes hardware verification a much more challenging job than hardware or software design. And because the fabrication cost of chips is so high, as much as possible has to be verified BEFORE fabrication, (no one likes a coaster, esp. when it costs in excess of 7-figure digits to fab). Without actual hardware to verify the hardware, all verification is done in software, through simulations, including the simulation of end user behavior, and the simulation of all the relevant pieces of the architectures under which the hardware is expected to be used. This is some serious testing. And this testing better simulate not only correct use with its humonguous state space, but also chaos pretty well. In fact, the only way to verify correctness is to introduce chaotic behavior in the test environment itself. By building randomness at each step of the input stimulus generation, chaos is introduced in the verification, and finds more bugs in more areas.

This is way more complicated than just using the same seed to reproduce a bug. This means that constraint random predictive stimulus generators, self checking scoreboards, automated test benches, and computer farms are needed to automate functional, formal and runtime verification. Actually, I don’t understand why these types of verification are classified under “software development” in the Wikipedia article on verification as they are used extensively in hardware verification.

OVM World Seminar, Ottawa – of database vs. object oriented code, and open source

Today I attended an OVM World seminar in Ottawa. There were three presentations. The first presentation was by Hans van der Schoot. Hans is a very interesting, brilliant and passionate engineer, which made this a fun presentation to watch. Shame on me for not having written down the names of the two other persons presenting after Hans: there was an engineer from Mentor and one from Doulos. All had presentations with lots of code examples in them, which to me is a plus.

Of database vs. object oriented code

A very common problem in ASIC verification is the modeling of configuration information. In typical object oriented code, you will build a nested structure of configuration objects, through which you access relevant information for different components of your environment, or for the DUT. For instance, when you access configuration, it may look like this:

  // Object Oriented approach
  Config config = new;
  ...
  config.pci_transactor[4].bfm.en_err_injection = 1;
  config.packet_scoreboard.tolerate_discards = 1;

In OVM, they propose an alternative to this form of nested strucure. It’s a database, indexed by strings:

  // Database-like approach
  ...
  set_config_int("pci_transactor_4.bfm.en_err_injection",1);
  set_config_int("packet_scoreboard.tolerate_discards",1);

You can also use wildcards in the argument strings. We are not far from using SQL syntax here! The main advantage of the database approach is that you do not need compile time binding of configuration objects. Say for instance you work on a block level environment where you do not have pci_transactors. Ideally, you do not even want pci_transactor configuration objects in your block level environment because they consume memory, create unnecessary dependencies, and extend you edit-recompile cycle. In Object Oriented code, it’s very hard to come up with the right structure to swap in and out those undesired members of the Config class. You can always do it with compiler #ifdef directives, but it’s hard. The database approach is more flexible. However, I would not be surprised if it cost more in terms of simulation speed.

A similar approach with the OVM Factory allows great flexibility when building an environment: instead of calling the constructor of your verification components directly, you can call a factory function, asking it for an object type with a simple string! The factory function returns an object of the specified type… or an overloaded version of your choice, which you specify in your testcase through another function. Let’s see this in code:

  // Call a factory function, cast the returned
  // object to a compatible instance
  Bfm bfm;
  $cast(bfm,create_component("Bfm","normal_bfm"));

Now the interesting part is you can instruct the factory function to replace the returned object of every call requesting a normal_bfm, to return a error_injection_bfm instead, like this:

// in the testcase
set_type_override("Bfm","error_injection_bfm");

Of course, all this requires registration of types and instances in a database, but it saves having to extend and overload instances in testcases. IMO it is always a big pain to overload existing instances at runtime because you must do it at the right time, between the build phase and the run phase, plus you have to redo the connections and the constructor (the new) arguments. It’s even a pain trying to explain it. I don’t know if SystemVerilog classes have static constructors, but I imagine this would be how their sole presence anywhere in a compilation unit resulted in their registration into a global database.

This concept can easily be extended to other aspects of verification environments, wherever deeply nested data structures are used.

OVM licensing questions

At the end of the seminar, there were many questions about the open source nature of the OVM. The answers in a nutshell: yes you can copy and redistribute it under the terms of the Apache 2.0 license (i.e. do not claim it’s yours, leave the copyright notice intact, etc. – read the license it’s all in there); no you do not have to make all your proprietary code publicly available just because you use an open source library if all you do is use the library internally for your own development.

Opening the OVM bug database

There was also insistance by some of the audience on the importance of making the OVM bug database open as well. Mentor and Cadence said they were tracking OVM bugs through their respective internal databases, but they were also trying to find a way to make these bugs public. One of the EDA vendor said they were going to publish known bugs using release notes at each OVM release, but that is not real time information about current bugs. But the nice thing is representatives from all three companies, Doulos, Mentor and Cadence all agreed that it was an important thing to do.

As far as reporting bugs through a public database, this is a delicate as anyone who has worked on project with a great number of users can attest: misunderstandings, duplicate bugs, and feature requests may eventually pollute the bug database. Not necessarily a big deal if users search through bugs before entering what they believe is a new bug, but most times users that hit the bug database have reach a high level of frustration, and they want their issue resolved now. Nevertheless, a public bug database is better than nothing at all. And the OVM user community is quite small compared say to a large open source project like gentoo, so I don’t think users will overwhelm the OVM developers with false/duplicate requests/bugs in the bug database.

Nothing stops anyone from opening a public bug database for the OVM and start using it… and same for creating a public repository for the source code as well. It is so simple now with the internet, I would chose savannah simply because it supports git, but any public server with a decent versioning tool would work.

Accepting contributions from the user community

There were two people asking on how they plan to accept contributions from the community. Their answer was that both Mentor and Cadence have people participating in the forums, and contributions made through the forums would be considered for inclusion in the OVM. The EDA representatives pointed out that contributions cannot be accepted as-is since they run tests on OVM before releasing it to insure its quality. I guess they could open source the OVM test suite as well. They could also use Linus’ philosophy: only grant write access to the source code database to trusted users with a proven track record of useful contributions or bug fixes.

ASIC register modeling

There were also talks about open sourcing the asic register modeling library, but no commitments were made. (I might have gotten the name wrong here since I am not a user of such library.)

OVM support

There were questions about support for the OVM: the EDA user community is accustomed to email support with EDA vendors. But the EDA guys really seemed hesitant to commit to email support for helping users with the OVM… I mean they are giving out the OVM source code under and open source license, and people expect free support? I think the EDA vendors do not have to provide free support for the OVM. I have paid for support of open source tools in the past and it’s the normal way of compensating someone for their time. Companies use linux and they still pay their IT staff to support the “free” OS!

One of my favorite way to obtain support is through public IRC channels. I get support for gentoo and Tango in their respective IRC channels. Of course, one cannot go to an IRC channel, get help, and never give back, because it is simply not fair: you are expected to give when you want to be part of a community, it’s not just about taking for yourself. Nevertheless, this maybe a good way for EDA vendors to provide support for the OVM: users helping users on an IRC channel on freenode, with OVM developers on the channel from time to time. After a while, users might be able to support themselves.

All right, that’s what I have to say about the OVM. I congratulate Mentor and Cadence on releasing the OVM under an open source license, a first for an EDA company!

Book review: Learn to Tango with D

On my never ending quest to find the utlimate language for ASIC Verification, I decided to learn DigitalMars D. Yes, it’s called D, as in A, B, C, C++, D. It is a compiled, object-oriented, garbage collected programming language which runs as fast as C/C++, without the hassles of C/C++ and without the verbosity of Java.

So I picked up a bit of D on my spare time, and then a book came out, Learn to Tango with D. D is the language, Tango is a systems library. My main worry about the book was that I am not a Java, nor a C/C++ programmer. But to understand the book, you do not need to know C/C++ or Java. The authors take the time to explain the concepts as they apply to D, which is really great. Most of the book is about D, and that’s perfect for me. Starting from chapter 6 is where the authors present the packages of the Tango library.

If you want to learn D, you could read the D manual, but it would be like reading a dictionary: long and dry. To me reading the online D manual was not enough, because there were things that I did not understand, such as the imports of modules, the use of the static keyword (what it really does), procedural lifetimes, and some intricate details of templates. All those and more are explained in the the book. The book also does a great job at explaining arrays. Arrays in D are awesome, and go above and beyond what you find in Vera. For instance, D dynamic arrays support slicing, which means you can have multiple references to the same data in memory, or portions of that data. Isn’t this great? Imagine how this could simplify and speed up nested packing/unpacking of data structures: your data would not move in the computer memory!

So can D be used for ASIC Verification? Well, you’d need a few things, such as threading and fixed sized integers, aka bit vectors of arbitrary size. The Tango library has Threads and Fibers, and with Fibers you can build coroutines, and with coroutines, you can build a simulator with mailboxes, semaphores, mutexes, etc. The first time I saw a demonstration that a simulator could be built with coroutines was in MyHDL but I am sure there are others. So I have no doubt a HVL simulator can be built with Tango Fibers. Tango also has a nice Logger package, meaning you don’t have to invent one.

D has assertions, which are equivalent to the boolean layer of SystemVerilog assertions. This is really an unfair comparison, since D was not designed as an HDL, nor as an HVL. If you need the full spectrum of HDL assertions, you’ll have a lot of work to do. Ideally, you’d also want a constraint solver, a constraint language, and something for functional coverage too. That’s a lot of things to be added before D can be used for ASIC Verification.

Nevertheless, D is great and I definitely recommend the book if you want to learn D and the important packages of the Tango library. The book has many code examples which greatly help understand the concepts.

SystemVerilog for Verification seminar

Today I attended a SystemVerilog for Verification seminar by XtremeEDA. This was a high quality presentation, with good slides (ie real code was on the slides and I like code since it’s what I do all day). It had been a while since I looked at SV in this amount of detail. I guess the last time was when I attended an SV presentation by Cliff Cummings, and before that it was when I looked at SuperLog presented by Simon Davidmann back when I worked at the Big Nerd Ranch.

There was about 40 people at the seminar, so I think it was well attended. There were questions about randomization and constraint solver, and so while I though those concepts were now well adopted and well known, it seems I was wrong. There were questions on controlling the randomness of simulations. I guess those concepts have not made it to CS and EE programs in universities, or some people are simply new to this and the seminar was the place to ask. There is a great book by Janick Bergeron on all of this, I highly recommend it.

I don’t want to describe how great SV is as a programming language, because frankly, you can all read about it everywhere on the internet. Personally, I like the asic-world website because it shows actual code. What I am mostly interested in is the features the language does not have, because it’s always those features that I ultimately miss. But here is the catch: I have not used SystemVerilog, only Vera! So there I go, I can’t even comment on features SV does not have, since I haven’t used it!

Nevertheless, I have 5 “directed” questions about SV:

1. Does SystemVerilog have covariant return types?
2. Does SystemVerilog have classes that I can use without declaring or creating an instance (in Vera I need to declare an instance, but I don’t need to create it)?
3. Does SystemVerilog have exception handling (throw, try-catch-finally)?
4. Does SystemVerilog have destructors (so I can deallocate stuff, or close some IO I created outside of SV)?
5. Are the functional coverage results stored in an open format like MySQL (it’s MY data, not the vendor’s)?

An interesting feature (or anti-feature) I learned about was that tasks can include time consuming statements, but don’t return a value, while functions do return a value (including void), but cannot consume time. Strange. Why would SV make a distinction, since it is annoying to have to use a task to consume time and return a value through an argument passed as a reference: why not have functions that can consume time? Distinguishing between tasks and functions is so… verilog! Strange or annoying I don’t know.

The assertions, aka SVA, look highly useful. They remind me of regular expressions, and I think that’s what they are: an entire state machine described as a one-liner cryptic expression.

Lastly, there will be a seminar by Cadence and Mentor on OVM in Ottawa on March 6th, 2008, I hope I can attend.

Hiring for ASIC Verification

You want to grow your asic verification team, and you decide you’re going to write a job description and post it with head hunters and on bulletin boards. You are looking for someone with HVL language experience like Vera, specman e, verilog or at least some vhdl experience. Perl is an asset. You have just removed 99% of all programmers in the world from your search. This is bad. You can’t afford to trim 99% of the potential candidates because they don’t know an HVL, because knowing an HVL is only a fortunate skill to have, one which can be acquired by reading a book.

One of the things your ASIC verification engineer will do is write a data structure parser for error injection or functional coverage, and you want this person to know specman ‘e’? Instead, you should wonder if this person knows how to write parsers. Otherwise, you will end up with “parser” on your schedule for every block-level environment you have, for every chip you ever do.

Someone who knows how to write a parser will create a recursive descent parser that your whole team can use by attaching a procedure to nodes being visited. You will be able to instantiate this parser anywhere in the verification environment where you have your data structure to parse. Someone who does not know how to write parsers will write one giant task in a scoreboard and manually travel down the data structure until the piece of interest is found. Nobody can reuse this parser because it is hardcoded inside the context where it is used. Any attempt of cut and paste to another place where it could be useful is doomed because the parser uses the scoreboard context instead of being self-contained.

I don’t think it’s an absolute necessity to know Vera or Specman, Verilog or VHDL to be able to do ASIC verification. Sure, it means the person has experience using those languages, but it does not mean they know how to program. Very few people know how to program in general. Of that, even fewer will know those weird proprietary programming languages that we use in ASIC verification. However, good programmers can learn new languages in a matter of a few weeks, and there is more good programmers that know C++, Java, Python and Ruby than there are good programmers that know Vera, Specman, Verilog or VHDL. So in the job posting, you need something that isn’t a turn off for 99% of the programmers.

In fact ASIC verification has little to do with hardware: writing parsers, creating entire libraries from scratch, writing your own mutually recursive functions to implement a constraint satisfaction solver, creating and data mining a post-synthesis timing database, are all things that I have done as part of so-called “hardware” verification. The problem is, those jobs are advertized with something like “verilog” as a requirement, and this simply turns off 99% of all software programmers because they think they will be playing with transistors all day and they’ve long determined that they wanted something more exciting like web 2.0, Ajax or JavaScript. Instead how about putting things like “combinatorics, QA, automated regressions, git and fan of Donald Knuth” in the ASIC verification job description.

ASIC Specification: how not to suck

I don’t know where bad ASIC specs started, but I suspect it was at the Big Nerd Ranch. ASIC designers would write a document describing their design, and voila, and ASIC Specification was born. Sorry, but when your write a description of your design, you are not telling me what you designed, you’re telling me how to designed it. Nobody really cares about HOW you implement the FizBoo feature. What I care about is whether you implemented FizBoo or not, how to program it, how to turn it off, and what it does.

The dictionary definition for specification is:

“a detailed description of how something should be done, made, etc.”

See, it should not even be called an ASIC Specification, because I don’t care how it’s made! Maybe you do, but I don’t! The ASIC Specification is the wrong thing to write. So let’s describe what kind of documentation I need as an ASIC Verification engineer:

1. Feature name (FizBoo) and short description (FizBoo scares little kids on halloween night).
2. How to program the feature, how to turn it off.
3. What the feature does to the data. If you can’t describe it in terms of a data tansformation, it’s not a feature and I won’t verify it, so why are you doing it?
4. What the functional interfaces are: am I talking to a PCI-X bus or a T1 interface?
5. A functional description of the functional interfaces: how do I twiggle the signals on that interface to make it tango baby?

See, I don’t care that you store 20 kilobytes of user data in a sea of flops or an internal RAM. I really don’t. I want to know how to get the data in there, not how you made the address decoder.

Except for one thing: I need to know your corner cases. Like “the data is cached in 32 words of 64 bits before being stored”. I will use this information to craft pieces of data that nicely align on 31 64-bit words. Or 33. Anything that will break your design will be my pleasure to try. But the internal RAM stuff, keep that for the back end squad. And why and how you arrived at the conclusion it was a RAM and not a sea of flops, I don’t really care either.

So how to write the ASIC spec then? First, don’t call it an ASIC spec. Call it a Detailed Feature Guide. The document should be a big “foreach loop”. For each feature, describe items 1 through 3 above. For items 4 and 5, they aren’t really attached to a particular feature, they are more like the boundaries of your system, like going through customs. They are related to a physical, geographical separation between the external world and the bowels of the ASIC. So this should be a separate document: the ASIC External Interfaces document. There are internal interfaces too, but you only need to document them on demand: places where BFMs will be probing/pulling for data, i.e. boundaries between the provinces of the ASIC country. So for the internal interfaces, have a 3rd document, the Internal Interfaces document, generated on demand only! You create this document only if others need to know how to interface with your internal stuff.

And while you are at it, why not engage the verification team early: they are the first customers of the ASIC, long before the software team. So instead of having them dream up a massive verification environment, have them write the Detailed Feature Guide. Of course, you’ll have to talk with them regarding the content, but let them do all typing and the editorial work while you are busy figuring out whether you use a RAM of a sea of flops.

Lastly, you should also engage the software team on all this. So have them write the Programming Guide while the verif team is busy writing the DFG. So what you have is a fully parallel documentation delta force working for you:

1. Verification team writes the Detail Feature Guide (DFG)
2. Software team writes the Programming Guide (PG)
3. Design team writes the Internal Interfaces Guide, only for the interfaces that are needed by the verif team (for BFMs), or the other designers interfacing to your sub-block.

Three documents, three teams, a triangle of power, a delta force at your service. D’oh! I forgot the backend squad! Here it goes:

4. Design team writes the Internal Description document, for all the things only backend cares about (RAM vs. sea of flops).

And for the External Interfaces document, I don’t really care who writes it, everyone needs to know whether it’s PCI or Utopia, and it’s usually already described somewhere else like in a standard.

At this point you are maybe getting anxious about having your verification team not writing the verification environment document or the verification plan, but they need the feature desription to know what to test, and the designers are usually overloaded towards the first half of a project translating marketing requirements into real world hardware. So have the verif team write the documentation they need. The verif team can develop their code while the designers write the RTL.

And bonus points if you find a way to cross refence external software register names between all 4 documents.