-
Notifications
You must be signed in to change notification settings - Fork 17
Best Practices
This is an attempt to capture best practice for coding style and organization when creating a pyrogue Device Tree.
If a .py file only has one Device class, name it with an underscore. Example:
_DeviceClassName.py
It is preferred to organize all Device classes this way, to make them easier to find.
Try to write Device classes that map directly to firmware modules. This makes the software more modular and makes it easier to determine the relationships to firmware. Give things the same name in both VHDL and Python when possible, such as:
- Device classes <-> VHDL entities
- Python packages <-> VHDL libraries
The Python package to VHDL library mapping can get a little tricky since VHDL doesn't have the concept of sub-libraries. It is encouraged to create python sub-packages that track the directory structure where the VHDL resides. Example:
python package: surf.axi.axi_lite <-> vhdl directory: surf/axi/axi-lite
The guiding principle behind all of this is that it should be easy to determine sofware/firmware mapping based on how things are named. There may be cases when it makes sense to deviate from this. When this happens, be sure to document in the Python code which firmware modules are being mapped.
Never do:
from somelibrary import *
It usually makes it clearer to eschew import as
and simply use the full package.module name in the code.
Only use import as
if it really saves verbosity, such as a long package path that is called multiple times in the code.
In the example below, the import as
doesn't really buy much, especially if only one class from surf.axi
is ever instantiated. It only creates a level of redirection for someone unfamiliar with the code would have to trace down.
import surf.axi as axi
...
self.add(axi.AxiVersion(...))
import surf.axi
...
self.add(surf.axi.AxiVersion(...))
import some.very.long.package.path as svlpp
...
self.add(svlpp.Device1())
self.add(svlpp.Device2())
self.add(svlpp.Device3())
self.add(svlpp.Device4())