Verilog project documentation

[mrflibble]

This is probably as good a section of the forum as any for this...

What do you guys use to document your HDL projects? Ideally I'd like something that uses the source code a la doxygen. So I'm currently having a stab at it with doxverilog (a set of patches against doxygen), but the results are a bit mixed.

For one it chokes on things like `default_nettype.

Anyways, I was just wondering what people use to keep their documentation in sync with the hdl source code...

[nctnico]

Write a specification first and then implement according to the spec. Seperating the design phase and implementation phase often leads to better products because it makes you think about the same problem twice in a different way. Tools like doxygen are completely useless because they don't show WHY something is implemented the way it is. A good IDE  (like Eclipse) also provides the information that doxygen produces but then in real time.

When I hire someone to develop code for me I do not accept doxygen output as documentation.

[free_electron]

Aldec has some really good tools.

if Code is written CLEAN it rarely needs inline documentation. the key is to make simplemodules and NOT instantiate other entities.
Where i work we have a number of internal rules : Top level is always a schematic. Each schematic drills down ot other schematics. at the lowest level sits a blob of verilog or vhdl.
Every module has its own file. no 'throwing everything in a single file'. Instantiating modules is a no-no. modules are to be connected at schematic level.

When a project is started the thing is partitioned in functional blocks and the buses and communication is defined. this all gets drawn as schematic. then particular blocks are assigned to particualr people or teams. those then get edit access to their block. they drop down a level and further subdivide in what they need. and so on. doing this makes locking and version control easy. anyone hase read access to the whole project but you only have write access to your portions. the 'top level schematic' is defined during meetings. this forces the designers to talk to each other and not go off and do things on their own.

the schematic is easy to navigate. They use Cadence Opus. just double click on a block and it opens in drill down mode.

i kinda do the same thing using quartus. toplevel schematic with pin definitions and then drill down.
if you need to re-wrie your schematic constantly it makes you think a bit more upfront ...

[mrflibble]

Write a specification first and then implement according to the spec. Seperating the design phase and implementation phase often leads to better products because it makes you think about the same problem twice in a different way.

Fully agreed on that.

Tools like doxygen are completely useless because they don't show WHY something is implemented the way it is.

That may have less to do with the tool, and more to do with the code monkeys you have been exposed to. I do understand what you mean however. Some of the "documentation" I've seen recently in some stm32 code exemplifies it nicely. Stuff like this:

Code: [Select]

    /* enable peripheral clock for pa and pc */
    RCC_AHB1PeriphClockCmd(RCC_AHB1Periph_GPIOA, ENABLE);
    RCC_AHB1PeriphClockCmd(RCC_AHB1Periph_GPIOC, ENABLE);


Enable clock for PA and PC? Really? NO SHIT SHERLOCK! Or blocks of code where they do things in a specific order ... all the subtasks are helpfully (hah!) described with noshitsherlock style comment. But evidently we don't need to explain why we do things in this particular order, nor do we need a description of the overall funtionality of what we're doing here. So I can understand your no doxygen rule, since it does invite people to mash on a keyboard and have the illusion of documentation. However in this scenario I am 1) the one person typing the code and 2) the primary victim if for some reason I decide to write crap documentation. So a healthy dose of self-interest will prevent noshitsherlock style comments. And possibly I might even try to write useful descriptions to be used by my future self.

A good IDE  (like Eclipse) also provides the information that doxygen produces but then in real time.

Soooo, know of any good eclipse plugins for verilog/system verilog? Preferably ones that do not break the bank... And it doesn't have to be eclipse, as long as it does the job. Because ISE project navigator does not do the job of "easily navigate your verilog project". Either that or I am using it the wrong way, in which case pointers on what is the right way are always welcome.

Oh and to clarify, this is for synthesizable code targeting xilinx fpga's. So not just verification and definitely no asic's in case that makes a difference for recommendations.

if Code is written CLEAN it rarely needs inline documentation. the key is to make simplemodules and NOT instantiate other entities.
Where i work we have a number of internal rules : Top level is always a schematic. Each schematic drills down ot other schematics. at the lowest level sits a blob of verilog or vhdl.

So how do you deal with a parametized array of instances? You could argue that "you should think more upfront", but that is a bit of a copout IMO. If you want to argue thinking upfront I should not have entered engineering but have become an arms dealer or somesuch. Or maybe something else borderline illegal and profitable like politics. So thinking upfront as defense for No Instances is out! ;-)

That aside I really wonder where the evil of instantiation is? Is this an ASIC company? Or are you targeting fpga's?

I do see the value of schematics however in that it makes the wiring of modules pretty much self-documenting. THAT is something that cannot be said for the instantiation approach.

Aldec has some really good tools.

I don't have any experience with Aldec tools, any in particular you would recommend looking into? Preferably ones that have an evaluation version...

[mrflibble]

Aldec has some really good tools.

Well, in the mean time I've been playing a little with SVEditor. It's not perfect, but at the very least it's better already compared to ISE. And it's free + in active development for a few years now.

I especially like being able to easily browse through my code + dig down into UVM classes.

And it's also got a "Generate Docs" button.

[free_electron]

So how do you deal with a parametized array of instances?
 Is this an ASIC company?
I do see the value of schematics however in that it makes the wiring of modules pretty much self-documenting. THAT is something that cannot be said for the instantiation approach.

[/quote]

no problemo. just make a separate verilog block where you define the parameters and do the instantiation in that block. NO OTHER CODE IS ALLOWED IN THIS BLOCK. we call this the instance wrapper. the instance wrapper gets its own schematic symbol which is then plonked down.
the block being instanciated again gets its top_level schematic block that then links to either sub blocks or the base verilog vode. when navigating : if you hit a block labeled 'instance_wrapper' you know to look for the same name to go on.

for example
pwm_instance_wrapper.v
pwm_instance_wrapper.sch  <- schematic block linking to the .v file.
pwm_instance.v <the pwm entity being instanciated
or
pwm_instance.sch <- the new toplevel for underlying stuff

so if i made  pwm channel consisting of a control block and the actual pwm block i would have two .v files:
pwm_control.v and pwm_engine.v
and 3 schematic files:

- pwm_control.sym
- and pwm_engine.sym ( symbols containing the input and outputs of the .v files as well as the parameters for them. )
- pwm_instance.sch a schematic showing how pwm_control.sym and pwm_engine.sym are wired up.

There would also be a pwm_instance.sym which show the input and output and parameter to the upper level ( by the way, the tools generate these .sym automatically. i don't need to do this. when a .v is 'precompiled' the .sym is created as well as a netlist for the place and route.

so now i could make a pwm_instance_wrapper.v and simply define that i need 16 pwm_instance.v's, define ther ethe inputs and outputs and feed the parameters down. the compiler will give me a new pwm_instance_wrapper.sym which i plunk down in my higher level schematic. and off i go.

Now , there are other reason for doing this approach : incremental compilation. by partitioning off at intermediate levels you can 'pre-synthesize blocks' and do timing closure , parasitic extraction and other stuff on them. this gets attached to the 'top-level' for that block and fed to the higher-up processors. in asic design the designer can close the timing , tune away parasitics and make sure the block meets the spec . the people assembling the blocks from various designers don't need to worry about what is in the block. you create clean boundaries.

on fpga you can do this as well. Tools like quartus have incremental compilation. if you need to resynthesize an fpga because of a modification you can shave off synth time. i have a system containing a customizable cpu core. A lot of this core is static (address busses, memories , io blocks etc. that stuff was compiled long ago , signed off , and works i never touch that. i only synthesize the bit that is new. instead of running for 30 hours the synth run is now 2 hours..

there is also an option in fpga tools to tell the tool : schematically added gates are not to be minimized. if you have a large system and have trouble with signal distribution and meeting setup and hold times you can simply plonk two inverters as schematic symbol in a clock wire to add some skew to meet setup and hold times. the synthesizer will not minimize those away. This is exactly how it is done in asics. we have specifiec clock buffers with specific drive strengths. the parasitic capacitance of a clocknet is extracted and the driver is tuned so that the setup times are met. if we need to go to the other side of the chip we simply add chains of buffers, each having its own delay so that everything falls into place. standard practice in the asic world. perfectly possible in fpga as well. all the fpga tools have that option.
there is even additional info in verilog where you can mark an entity written as a netlist not to be minimized ( but it is faster to draw this than trying to code it )

i have a block , drawn as schematic that creates a programmable skew on signal. it is a chain of invertors ( each invertor is 410 picoseconds in the fpga i use so each 'tap in the chain gives me 810 picoseconds. the taps go through a balanced and/or network so that i have a skew programmable from 1.9 nanosecond to roughly 10 nanoseonds in steps of 810 picoseconds. under control of a register that is dynamically alterable.

i have a serial bus clocked at 120 Mhz on my board this thing is routed over backplanes and goes to a lot of things. Depending on what i am talking to i simply reprogram the skew on the signals so that they arrive at the other board at that chip's pins with the right setup and hold time. i f i talk to a close-by chip the timing settings are different than for a chip on a different board half a meter away. i don't need to muck about with difficult board layout , or crazy constructions. the system simply loads a different 'skew' setting and talks. i can even time-shft the returning signals so they coincide with 'earlier' clocks that were time-delayed on the fly. no need for resyncing no wasted clockticks , no need for pipelining .. it all goes away. during powerup the timing is even self-searching. a specific pattern on the bus causes the target chip to toggle its return line in phase with the clock it receives. i keep blasting that pattern over and over and an exo rgate compares my outgoing clock to the returning 'clock' through the data line. the moment i detect a clock i know my outgoing timing is correct as the chip now responds. now i can align my returning data by changing the skew block there until the rturn clock is phase aligned witht heoutgoing clock. done.

at boot time the main processor scans the bus in this way , determines the timings for each of the slaves and off we go. if somebody moves a slave board to a different slot so it sits physically further or nearer a simpy power cycle will determine the new timings. the system is entirely adaptive.

i use this in harddisks. here is the problem : you have chip that sits in a temperatur chamber while the other half of the board lays outside and is connected with a meter of wiring. when done you remove the cabling... oh crap... all the timing is now messed up. this adaptive system has no problems. throw cable in there ( withing reason : the delay needs to be in the catching range of my skew block ) and the system will self adapt on power cycle. )
if they decide to move the chip to a different corner of the board i dont need to worry about anythin. on every powerup the timing is returned. you can put that chip on the moon for all i care. the logic re-times everything.

2) yes this is asic work , but i apply the same techniques on fpga. it is a matter of discipline. keep it clean , and use the schematics as your navigator. A digital system typcially has a bus like structure on board talking to a cpu. define that bus as your toplevel . one level down you get all the bus signals. and you keep propagating down. you can prpagate parameters up ( like base addresses for a functional block )
say you got a gpoio sub block a uart sub block a dpram sub block etc. you can push parameters up to give the base address down. the bus decoders reside in the individual blocks and work off the fed parameter. need to change the moemry map ? change the parameters at the top level. done. the whole pile becomes self documenting. in 1 sheet you have all the info you need : pinout , memory allocation , skew control. and each team or person can go off and work in his own allocated sub block while the top-level guys are already mapping out the io cells and board guys are starting layout as well. it can all be done in parallel and everything will fall into place at the end.

3) and that is exaclty why , for big asics, the toplevels are still schematics. besides, even in a pure dgital chip there is still a lot of analog muckery. digital is nothing more than a very narrowly defined case of analog ... think about MLc flash for example.  data is stored in analog...

[mrflibble]

no problemo. just make a separate verilog block where you define the parameters and do the instantiation in that block. NO OTHER CODE IS ALLOWED IN THIS BLOCK. we call this the instance wrapper. the instance wrapper gets its own schematic symbol which is then plonked down.

I understand using a wrapper, but I actually meant it for the compile time decision of parameters. That's why I also asked if this was for ASIC. I can understand that things are a lot more rigid there, and with good reason.

But for the small stuff I do I find it handy to be able to change some parameters of the design at compile time. Well, synthesis time. Especially when I am testing a few design options.

So for the wrapper things are obvious, but the variable amount of wires coming out of it ... how do you deal with that in the schematic above it? Lets go with the most obvious example, parameterized bus width. If the schematic can handle the variable bus width coming out of the wrapper then that's neat. If however you need a new wrapper (or new schematic) for each variation in bus width parameter ... then that would get annoying real fast. Maybe that annoyance has it's place in ASIC where some rigidity is good. But as said, for the small stuff I do that would get annoying real fast.

Protection against human error, all for it. Rigidity for rigidity's sake, not a big fan. But I suspect that for big ASICs the protection against human error feature outweighs the annoyance.

What specific tool do you use for the schematic stuff?

Now , there are other reason for doing this approach : incremental compilation. by partitioning off at intermediate levels you can 'pre-synthesize blocks' and do timing closure , parasitic extraction and other stuff on them. this gets attached to the 'top-level' for that block and fed to the higher-up processors. in asic design the designer can close the timing , tune away parasitics and make sure the block meets the spec . the people assembling the blocks from various designers don't need to worry about what is in the block. you create clean boundaries.

Yeah, incremental is a big item on my todo list. So far I've always done it in 1 big go because that's easier to set up. But for some projects it would be nice to just place & route certain parts of it once, and then only recompile the new bits. The main reason for me would be to reduce time spent waiting on the tools.

there is also an option in fpga tools to tell the tool : schematically added gates are not to be minimized.

Yeah, you have the same sort of thing for non-schematic stuff as well. Although, you say "option" and not "constraint". I typically use a constraint to make sure certain important bits are not optimized away. But maybe you meant it as a synthesis option, which would be handy.

The auto-calibrating delay stuff sounds nifty. As for the delay element itself, on fpga one can be relatively lazy what with the IODELAY elements builtin to the IOBs.

2) yes this is asic work , but i apply the same techniques on fpga. it is a matter of discipline. keep it clean , and use the schematics as your navigator. A digital system typcially has a bus like structure on board talking to a cpu. define that bus as your toplevel . one level down you get all the bus signals. and you keep propagating down. you can prpagate parameters up ( like base addresses for a functional block )

I can see how schematic would help for navigation. The problem here is xilinx tools are a bit crappy, certainly in terms of navigation. Right now I am in the process of moving more to System Verilog, and as such that means at the very least a different editor + simulator. Which means moving away from xilinx integrated tools, which means even less chance of using the schematic tools in there...

[free_electron]

You're not on sv yet ? Drop xilinx and switch to altera.
Nothing wrong with xilinx in itself , but they have a different mindset.
Xilinx caters to the million gate crowd and assumes those guys will use synopsys anyway. So their ise is a simple frontend and all the focus lays on the backend. In other words doing the DESIGN in ise is crap.

Atera targets small to intermediate devices and users that do not want to shell out for synopsys. So their front end tools are better.

[mrflibble]

Yeah, still mostly on plain ole boring verilog. Precisely due to the tool situation.

If Altera magically solved all my problems I'd jump ship in a second. Well, several seconds anyway. I am however aware of this wonderful human grass-greener-over-there tendency...

So how is altera for both SV synthesis and simulation? Especially on the synthesis side, does quartus support the same amount of constructs as say something like synplify pro?

[free_electron]

not close to synplify , but the synth can handle V2005 syntax and is fully compliant.
for sim you use modelsim-quartus edition. i assume that one can handle v2005

i always write my constructs in v2005. lots less typing,  constructions like always_ff always_latch allow fine tuning and upfront problem elimination

[mrflibble]

Mmmh, not the resounding "IT SUPPORTS EVERYTHINGGGG" I was misguidedly hoping for.

So a bit better than xilinx and a bit worse than synplify. Does it support things like interfaces and .* port lists?

[mrflibble]

Oh yeah, forgot to ask. Does the Altera included simulator also have UVM support, or is that one bridge too far?

[free_electron]

.* port lists yes. that is part of V2005 standard. uvm. no clue