I consider that spec reading and comprehension is a critical part of the verification flow. All following stages in a verification project depend on this activity and that’s why every junior engineer who joins AMIQ goes first through a specification reading crash course.
I present below a set of guidelines that AMIQ engineers follow. Enjoy!
Be curious: a specification is a journey worth taking
To read a specification can be quite a journey and curiosity is one’s most trusted guide. You will encounter interesting problems and creative solutions that will give you a new perspective on what and how it can be done.
Most of the times the spec is not in a good shape, to say the least, but that’s part of the journey, an invitation to contribute, to make it better.
Be patient: reading a spec is a process
You should be aware that reading and understanding a spec are laborious processes, so cut yourself some slack. You might need to go through it in successive iterations. Every iteration you need to communicate with designers, system architects or software engineers and that takes time. Also consider that even designers don’t know everything, so be kind and help them clarify the spec.
Learn: a spec is a crash course on a specific subject
Reading the spec gives one the opportunity to learn new techniques, to acquire architecture and implementation know-how on a specific subject. I can imagine that after a number of years of reading specs one could start contribute to design solutions. With every spec that you read you will get more accustomed with the technical terminology.
Contribute: it’s your spec as well
Approach the spec as if it would be yours: you’ll have to live with it for the rest of the project. It’s your responsibility as a verification engineer to make it better, to remove any inconsistencies, things that you find correct, to make it as neat and detailed as you like. Don’t turn your back to it, don’t throw it in designer’s yard, it will come back to you when you expect the least, always in an unpleasant way.
You can always help the designer by writing paragraphs or drawing figures that illustrate the concepts.
Be neurotic
It’s OK to be neurotic, it’s even required. All of the following should unsettle you: spelling mistakes, formatting inconsistencies, lack of page numbers, lack of a table of contents, header/footer’s contents, the size of the fonts, the wording, the verbs, the grammar, if the style is too colorful, the words you don’t understand, ambiguous expressions, missing links, missing references, document’s title, consistency of naming conventions for signals, registers, functions, modules, classes, interfaces, if it uses camel_case or camelCase, pieces of code, untitled tables and diagrams, missing pictures, or too many pictures and no words, state machines described with words instead of diagrams, unclear flow descriptions, inconsistent styles used.
Be imaginative
You should try and imagine the scenarios that break the spec, the scenarios that are not covered by the specification, that will crash everything. You discuss those with the designer and hold your ground until either the designer will bring evidence the scenario is impossible to achieve or that it might be possible and there is a way to handle it.
What-if should be your second nature.
Beware the details
Details are appealing, but dangerous. Don’t jump directly into the details, allow the information to layer naturally with every read. In the beginning you should consider learning the big architectural features of the DUT: scope, goals, interfaces, internal architecture, etc. With every read dive deeper, clarify and correct more.
It’s like building a house: you start from a blueprint, go through foundation, frame, …., down to the picture on the wall. Not vice-versa!
Read the spec with a meaningful goal
How do you know when you are done? Is it enough to say: “I’ve got it!”?
Definitely not! The process called “understanding the spec” is part of the verification planning phase and the result of this step should be another document: the verification plan which contains what is to be verified and the strategy/tactics to achieve that. Start working on the verification plan with the first read and refine it as you progress through specification. It depends on the company, but you’ll be required to fill one or more documents that make the verification plan.
Every journey starts with the a step, every spec starts at first page
I suggest to you start with the first page and continue in order one page at a time; if you follow through a reference, always come back to the place(page, paragraph, sentence, word) you left from. If you think following a reference or searching a concept it will take too long, just write it down and revisit it later and continue reading; you will not understand maybe what’s about on the spot, but you don’t lose focus.
You should focus on the big picture the first time around. As you progress along, write down things that puzzle you, that should be corrected, that maybe are missing, scenarios or ideas that come along.
Every journey comes to an end
When you feel confident enough in the verification plan, you should ask for a review. The review will highlight weak spots and redundancies in the spec or verification plan. There can be multiple review-fix iterations.
A fun exercise
A fun exercise to do is to imagine your own solutions to the problems the spec presents, before you dive deep into implementation details. As you are getting closer to an end compare your solution with the one given by the spec.
This article is part of a methodology articles series that I plan to write, so stay tuned.
One Response