Best practices for "cores" development (GSoC 2016 projects)

This post contains best practice guidelines for creating MyHDL based projects.


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>

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

  1. 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

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.

def beh_combinatorial_logic():
    # comb behavior goes here

State machines


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.

@jck, @josyb can you guys add to the best practices and then I will send out an invite to all the GSoC students to discourse.

A few additions:

  • All dependencies must be in install_requires (
  • All dependencies which are not on PyPI (like the dev version of myhdl ) must be placed in requirements.txt as well.
  • All code must be Python 3 compatible; Python 2 support is optional. Students should not use any deprecated features, and are free to write Python 3 only code if it allows cleaner code.
  • All code must use the new method based API.
  • Keep commit history clean. Write descriptive commit messages, and feel free to use interactive rebase on your branches before creating PRs, and feel free to rebase existing PRs after you address all inline comments. See and for examples. I’ll add more to this, I’m going to dig up some good articles I’ve read.

Regarding package versions, might I suggest using setuptools_scm? It’s really clean, it automatically infers the version based on the git tag.

I’ve setup the riscv repository:
Since MyHDL 1.0 isn’t released yet(and hence not on PyPI), it is necessary to manually install the dev version of MyHDL into the virtualenv(or by using pip install -r requirements.txt . However, eventually all packages should be directly pip installable in a clean virtualenv and this should work: pip install git+

@jck I made this post a “wiki” post are you able to edit it directly? If not do you know what I need to do so you can?