pio2o

Overview

pio2o is a Python program that generates an Oberon module to get the binary code for PIO assembly programs.

pio2o does two steps:

run the PIO assembler pioasm to create the corresponding binaries;
generate an Oberon module to read this binary code, to then load it into the PIO instruction registers.

There can be more than one PIO program per module, and .wrap and .wrap_target are supported.

The Python version used to develop the program is 3.12.

Description

The PIO assembly code can either be

placed inside comments and two keywords directly in an Oberon module, or
read from a separate file.

Inside an Oberon module, from the example program:

(*
  PIOBEGIN
    .program square_wave
      set pindirs 1
    loop:
      set pins 1 [1]
      set pins 0
      jmp loop

    .program square_wave_asym
      set pindirs 1
      .wrap_target
      set pins 1 [1]
      set pins 0
      .wrap
  PIOEND
*)

This results in the following Oberon code – see the example program how to use GetCode to load the PIO code into the PIO devices, and configure the state machines.

  IMPORT PIO;

  PROCEDURE GetCode*(progName: ARRAY OF CHAR; VAR prog: PIO.Program);
    VAR i: INTEGER;
  BEGIN
    IF progName = "square_wave" THEN
      prog.name := "square_wave";
      prog.wrapTarget := 0;
      prog.wrap := 3;
      prog.origin := -1;
      prog.sideset.size := 0;
      prog.sideset.optional := FALSE;
      prog.sideset.pindirs := FALSE;
      prog.instr[0] := 0E081H;
      prog.instr[1] := 0E101H;
      prog.instr[2] := 0E000H;
      prog.instr[3] := 00001H;
      prog.numInstr := 4;
      prog.numPubLabels := 0;
      prog.pubSymbols.numGlobals := 0;
      prog.pubSymbols.numLocals := 0;
      i := prog.numPubLabels;
      WHILE i < PIO.NumDefs DO;
        CLEAR(prog.pubLabels[i]); INC(i)
      END;
      i := prog.pubSymbols.numGlobals;
      WHILE i < PIO.NumDefs DO;
        CLEAR(prog.pubSymbols.global[i]); INC(i)
      END;
      i := prog.pubSymbols.numLocals;
      WHILE i < PIO.NumDefs DO;
        CLEAR(prog.pubSymbols.local[i]); INC(i)
      END
    ELSIF progName = "square_wave_asym" THEN
      prog.name := "square_wave_asym";
      prog.wrapTarget := 1;
      prog.wrap := 2;
      prog.origin := -1;
      prog.sideset.size := 0;
      prog.sideset.optional := FALSE;
      prog.sideset.pindirs := FALSE;
      prog.instr[0] := 0E081H;
      prog.instr[1] := 0E101H;
      prog.instr[2] := 0E000H;
      prog.numInstr := 3;
      prog.numPubLabels := 0;
      prog.pubSymbols.numGlobals := 0;
      prog.pubSymbols.numLocals := 0;
      i := prog.numPubLabels;
      WHILE i < PIO.NumDefs DO;
        CLEAR(prog.pubLabels[i]); INC(i)
      END;
      i := prog.pubSymbols.numGlobals;
      WHILE i < PIO.NumDefs DO;
        CLEAR(prog.pubSymbols.global[i]); INC(i)
      END;
      i := prog.pubSymbols.numLocals;
      WHILE i < PIO.NumDefs DO;
        CLEAR(prog.pubSymbols.local[i]); INC(i)
      END
    END
  END GetCode;

Everything within the PIOBEGIN and PIOEND markers must comply with the PIO assembly language specifications, including comment styles (/* .. */, //, ;).

In a separate pure PIO assembly code .pio file, the PIOBEGIN and PIOEND markers are omitted, of course.

The PIO programs’ binary code and the .wrap and .wrap_target parameters are read from pioasm’s JSON output. JSON data is only available with pioasm v2.x, hence this newer version is required (see below).

Example Program

Please refer to example program PIOsquare.

Platforms

Both Windows and macOS are supported.

Installation for Command Line Usage

This is how I install and run pio2o:

put pio2o.py into any directory, which must be on $PYTHONPATH, though;
one possibility is to leave the file in its directory in the repo structure, so you get and “install” any updates automatically. Just put the directory on $PYTHONPATH;
run the program with the -m option for Python (without the .py extension).

Hence, to generate the Oberon module for the example PIOsquare, I run in the shell, inside the example code directory (with pioasm installed as described below):

> python -m pio2o PIOsquare.mod

> python -m pio2o PIOsquare.pio

Which both generate PIOsquarePio.mod, that is, Pio gets added to the source module name. You can optionally specify a different output module name using -o module_name.

Running

> python -m pio2o -h

prints

usage: pio2o [-h] [--verbose] [-o MODULE] [-v VERSION] ifn

Create an Oberon module for PIO assembly code. 'pioasm' is used to assemble
the PIO code, which then can be accessed from the Oberon module.

positional arguments:
  ifn            input file (.mod or .pio)

options:
  -h, --help     show this help message and exit
  --verbose      print feedback
  -o MODULE      Oberon output module name
  -v VERSION     default pioasm version (0 or 1, default: 1)

PIO source code can be extracted from an Oberon module (.mod), or read from a
separate file (.pio). In the Oberon module, place the code inside a comment and
keywords PIOBEGIN and PIOEND.

Install as outlined above, then add this snippet – mutatis mutandis – to your Tools.ini file in the Astrobe configs folder:

[Command3]
MenuItem=Create PIO Module
Path=C:\Users\gray\AppData\Local\Programs\Python\Python312\python.exe
Parameters=-m pio2o %FileDir%\%FileName%
WorkingFolder=%FileDir%
ConsoleApp=TRUE
Prompt=FALSE

PIO Code Assembler pioasm

pio2o relies on the PIO assembler pioasm in the Raspberry Pi Pico C SDK. Just the binary! No need to touch the SDK otherwise. :)

The easiest way to obtain pioasm is to download the binaries from https://github.com/raspberrypi/pico-sdk-tools, and copy them into a directory on the $PATH. On Windows, I put them into 'C:\Program Files\Raspberry Pi\bin', on macOS into 'usr/local/bin'.

Important: the older version of pioasm in pre 2.x versions of the SDK does not work, since it does not provide JSON output.

Repository

pio2o.py