This post contains best practice guidelines for creating MyHDL based projects.
Versions
The 2016 GSoC projects will use MyHDL version 1.0dev. The version has not been released (yet) and needs to be installed manually. It is suggested to a requirements.txt and pip install -r requirements.txt to retrieve the 1.0dev version.
The projects will use Python3 and Python2 support is optional.
Python package structure
Each project will be structured as a Python package and will use one of the suggested py.test structures for the test code.
Recommended package structure:
<github repo name>
docs/
<project_name>/
requirements.txt
setup.py
tests/
For the project name, follow the Python package names conventions [need reference]. The package names are all lowercase and underscore used to separate long names, use the “_” sparingly. See the Python standard library for some examples of package names (argparse, queue, collections, etc.)
Suggested names for the five packages being developed:
pyleros/ # Leros microcontroller
jpegenc/ # (M)JPEG encoder
gemac/ # gemac
hdmi/ # HDMI transmit and receive
riscv/ # RISCV CPU and tools
Testing structure
Lots of test will be written, define and implement your interfaces and transactors. Build tests utilizing the interfaces. Verify the tests fail and the interfaces transactors look like they are doing something reasonable.
Python coding
Follow the PEP8 coding guidelines.
HDL coding
Follow the PEP8 coding guidelines.
HDL PEP8 exceptions
- Line lengths greater than 90 columns but use sparingly it is convenient to follow the narrow column coding guidelines when using multiple editor frames.
HDL design patterns
The following outlines common design patterns used in HDL.
HDL structure with blocks
@myhdl.block
def myblock(*port, **parameters):
name1_inst = mysubblock()
name2_inst = myothersubblock()
return myhdl.instances()
Sequential logic
Refer to the sequential logic section of the myhdl manual. The following is a template for sequential logic.
@always_seq(clock.posedge, reset=reset)
def beh_sequential_logic():
# sequential behavior goes here
Combinatorial logic
Refer to the combinatorial logic section of the manual. The following is a template.
@always_comb
def beh_combinatorial_logic():
# comb behavior goes here
State machines
Documentation
Documentation is very important for the cores being developed. Others should be able to use the cores with little difficulty. The documentation should cover user and developer. The user documentation has enough information for someone to use the core with many examples. The developer documentation outlines various aspects of the design.
Fortunately Python ecosystem has tools that help simplify documentation. Sphinx and readthedocs should be used for the documentation system.
For each block and interface use google style docstrings. Every block, interface, and function that is commit should have a docstring and the global documentation should be updated (minimal is to include the docstring with autodoc)
Using virtualenv
Create environments with virtualenv this will allow the developer to seamlessly switch between python, myhdl, and dependency versions.