Functionality without an interface doesn’t exist.
In reading several blogs and newsletters recently I’ve gotten annoyed that people don’t say what they mean. There is talk about how to design better interfaces and how to document them better but this misses the point that without the interface any possible functionality doesn’t exist. Further the authors never get around to simply stating
Design the Interface First.
To unravel this though:
Jakob recently introduced me to Gary’s newsletter. So I started reading the back issues. Two in particular The (not so) Exciting World of Documentation and Accurate Register Specifications caught my attention. In the first Gary talks about the trouble generating accurate documentation for hardware designs and suggest that hardware engineers have firmware engineers review the documentation to ensure that it is comprehensible. He also discusses the difficulty in documenting the interface after the fact. In the second Gary suggests using a register design tool. Jakob then comments on this in his blog stating
“You really need a full expressive language to write a truly executable model of the hardware.”
Now all of this is well and good, and I happen to agree, but why do they go on at such length about their topics instead of just getting to the my point:
Design, document, and declare the interface first, then worry about implementing any functionality that may be triggered by calls to/interactions with that interface. Without the interface the functionality doesn’t exist.
I feel particular passion about this topic because of a situation I’ve run into with a customer with where over a year ago we were told (paraphrased)
We can’t give you the documentation on the interface to, or basic functionality of, our part in time for you to complete a high level functional model 6 months from now; we haven’t designed the interface and the documentation hasn’t been started. However we have the detailed model almost done we can integrate our detailed model with the functional framework in plenty of time.
I didn’t believe this at the time, and the detailed model ended up being about 3 months late before the integration really started working. The interface to the functionality is still being updated and the documentation still isn’t complete. Further as the firmware and unit tests gets written it becomes increasingly clear that the interface was never “designed” as such, rather it was just slapped together with the hope that it was good enough. Cases are still being found where functionality can’t be tested because there is no interface to it.
From this I draw the conclusion: functionality doesn’t exist until it has been tested through a well designed external interface, simply writing the RTL isn’t enough.
[edit]
Jakob points out that he did present this sentiment but not quite as clearly as I would have liked.