pymoku-sdk 0.3

CLI tool to create pymoku projects

Getting Started

Prerequisites

Simulation

Simulations are run in a docker container with the image li-cocotb-pymoku. You will need a docker environment with access to this image (currently unpublished).

The resulting wave.ghw files can be viewed with GtkWave or Surfer.

Building bitstreams

Vivado

Bitstreams require a local verision of Vivado (>= 2024.2 recommended) installed with appropriate licences configured.

TODO

Parts can be exteneded to package build context for a remote worker, avoiding the need for a local Vivado installation.

Keys

Creating barfiles that can be deployed on a Moku require them to be signed by Liquid Instruments or with developer keys that have been enabled on the target Moku.

See below for generating keys; these must be signed by Liquid Instruments to enable specific devices.

(interim) Installation

These are the current instructions until these packages are publicly available. It does require access to the LI internal GitLab.

Put these in requirements.txt

pymoku @ git+https://git.liquidinstruments.com/pymoku/pymoku.git
pymoku-parts @ git+https://git.liquidinstruments.com/pymoku/pymoku-parts.git
pymoku-sdk @ git+https://git.liquidinstruments.com/pymoku/pymoku-sdk.git
docker

create a virtual environment

python -m virtualenv venv
source venv/bin/activate

and then run

pip install -r requirements.txt

Generate a signing key

This only needs to be done once, and the key will be stored in the user home directory.

pymokusdk keys create my-key

The resulting public key will need to be signed by Liquid Instruments.

Create a new project

pymokusdk new MySlot --hw mokugo
cd myslot

Run the simulaition

parts tests

Results will available in the build/test-slot folder. Of interest will be wave.ghw and stdout.log. Build failures in the VHDL will be printed to the console, but errors during execution will be stdout.log.

Run a build

parts mokugo python --stats

The resulting barfiles will be in output/.

Deploying from Python

import pymoku
pymoku.plugins.DEV_CACHE = './output'  # reference our local output
moku = pymoku.connect('10.0.0.1')
moku.deploy_platform('pymoku:platform_2')  # deploy a platform (only needed once)
myslot = moku.deploy('custom:myslot')  # this name should match the specific id used in parts.def

The myslot object will be created dynamically from your custom python plugin and attached to the slot instance on the Moku.

Deploying from the GUI

First you will need to have installed pymoku[extras] to include GUI support.

Then run pymoku with reference to your local output folder

pymoku --dev output/

This will launch the GUI. After connecting to a Moku and deploying a platform, your custom implementation will be available from the functions palette (assuming it was built for the deployed platform).

Launching the slot instance will open the applet defined by your custom python plugin. The default will appear as a python console.

TODO

• 'clean' targets
• Create barfiles for checkpoints to use as platforms
• Don't use GPG for signatures
• Use personal signing keys to sign manifests
• Generate signing keys
• Auto generate "custom wrapper"
• Bitstream encryption
• Sanity check environment
• Fetch checkpoints from cloud
• Plugin versions (or lack of) break pymoku prioritisation
• API deployment
• If Git on PATH or CLI arg, add .gitignore and init repo
• Auto generate top/test bench with new generics and custom number of Ain/Aout