RTL code, or any other code for that matter, is rarely written from scratch. Usually you start your design based on someone else’s code. So to make your code easier to understand for your colleagues or any other person that want to use it, consider these two simple design rules.
Divide your design into structural and functional blocks
A structural block is a block that only contain instances of other blocks and the interconnects between them. A functional block contains logic, registers, memories, and all other neat stuff you want to put in your design.
Most designs have this division naturally. A design is usually a bunch of functional blocks that are connected together in a higher level block.
What is important is to resist the urge to add logic in a structural block, even though this may be the easiest place to fix a bug or change the functionality to match your needs. This is for two reasons:
- Logic outside a functional block will not be included when the block is copied or re-used in other designs, leading to higher risk of bugs.
- It is not clear who is responsible for the logic in a structural block.
Use this convention, and no logic will be forgotten or misplaced.
Use special names for I/O signals and interconnects
This naming convention makes it much easier to see the structure of the design for a person that is new to the code.
- I/O signals get a reserved prefix. For example:
- Input signals are named i_<signal_name>
- Output signals are named o_<signal_name>
- Interconnect signals between blocks are named <driver_instance>_<signal_name>
An example is shown in the picture below.
If these conventions are used it is always clear whether a port of an instantiated block is an input or an output. The driver of a signal can also be easily seen from the name of the signal. So no more backwards tracing of signals in huge interconnect blocks.
Happy code sharing!
Note: if you use VHDL for coding it is not allowed to read output ports. To get around this problem it is common practice to use an internal signal as an alias for the output port, and then connect the alias signal to the output port. It is a good idea to use special names for these alias signals too, such as a_<signal_name> .