pypepp 0.15.1

Python bindings for the Pepp assembler and simulator

Pepp

Table of Contents

1. Building for Source
2. Previous Works
3. Pep/9 and /10 Virtual Machines
4. Project Features
5. Contributing
6. Making Modifications

Build from Sources

When cloning this project, use --recurse-submodules to install relevant source code dependencies.

Required Build Tools	Reason
Qt 6.10 or later	Required for cross-platform GUIs. Under "Additional libraries", install Qt WebEngine and Qt WebView
CMake 3.24 or later	Required build system; usually bundled with Qt
git lfs	Required for binary assets, such as images an icons
Python 3.12+	Required for python bindings and compile-time changelog. Must be on your path.

While not required, the following tools enable additional features in built applications:

Optional Build Tools	Reason
Qt Creator 14 or later	Preferred IDE for this project
QT IFW 4.7 or later	Creates Windows installers

It is recommended to build the application from within Qt Creator.

Additional Windows Build Steps

On Windows, the default build process does not set QML plugin search paths correctly. In most cases, this prevents the application from being run in Qt Creator or from the command line.

This is fixed with a custom build step. This build step must be added to each build configuration (e.g., build, release).

Line	Value	Description
Command	<QT_ROOT>/bin/windeployqt6.exe	On my PC, <QT_ROOT> is C:/Qt/6.9.1/msvc2022_64
Arguments	%{buildDir}\output\pepp.exe --qmldir %{sourceDir}	--qmldir is required for discovery of our dependencies
Working Directory	(blank)	This value does not matter and is unused

Relation to Pep9Suite

This project is a continuation of the Pep/9 computer's associated software suite, Pep9Suite.

When complete, this project will contain assembler and microcode simulators for Pep/8, Pep/9, and Pep/10, and we will deprecate older repos.

The goal for this new project is to reduce cross-generation maintenance, improve reliability, and reduce turn-around time for new features.

What are Pep/10 and Pep/9

Pep/10

The Pep/10 computer is a 16-bit complex instruction set computer (CISC). It is designed to teach computer architecture, assembly language programming, and computer organization principles as described in a future book. Pep/10 instructions are based on an expanding opcode and are either unary (one byte) or nonunary (three bytes). The eight addressing modes and six dot commands are designed for straightforward translation from C to assembly language.

It includes macros facilities to ease translation from C to assembly language.

Pep/9

The Pep/9 computer is a 16-bit complex instruction set computer (CISC). It is designed to teach computer architecture, assembly language programming, and computer organization principles as described in the text Computer Systems, J. Stanley Warford, 5th edition. Pep/9 instructions are based on an expanding opcode and are either unary (one byte) or nonunary (three bytes). The eight addressing modes and eight dot commands are designed for straightforward translation from C to assembly language.

What is Pepp?

The Pep project consists of many iterations of a 16-bit complex instruction set computer . Within this repository, the Pep/10 version (and soon the Pep/8 and Pep/9 versions) are represented across multiple levels of abstraction.

The project now consists of a single download for all virtual machines at all levels of abstraction. The terminal version was previously a stand-alone executable and is now part of the main download.

Assembler

Our Pepp IDE features an integrated text editor, error messages in red type that are inserted within the source code at the place where the error is detected, student-friendly machine language object code in hexadecimal format, the ability to code directly in machine language, bypassing the assembler.

The Pep/9 computer features the ability to redefine the mnemonics for the unimplemented opcodes that trigger synchronous traps.

The Pep/10 computer features the ability to define custom macros.

ISA

The simulator features simulated ROM that is not altered by store instructions, a small operating system burned into simulated ROM that includes a loader and a trap handler system, an integrated debugger that allows for break points, single and multi step execution, CPU tracing, and memory tracing, the option to trace an application, the loader, or the operating system, the ability to recover from endless loops, and the ability to modify the operating system by designing new trap handlers for the unimplemented opcodes.

Microcode

The CPU mode is a simulator allowing users to interact with the data sections of the Pep/9 and Pep/10 CPUs.

It contains two versions of the Pep/9 CPU data section – one with a one-byte wide data bus and another with a two-byte wide data bus. Using a GUI, students are able to set the control signals to direct the flow of data and change the state of the CPU. Alternatively, the Microcode IDE allows students to write microprogram code fragments to perform useful computations. An integrated unit test facility allows users to write pre- and post-conditions to verify correct behavior of arbitrary microprograms.

While debugging a microprogram fragment, the CPU simulator performs graphical tracing of data paths through the CPU. Using breakpoints, students may skip over previously debugged microstatments and resume debugging at a later point in the program.

ISA / Microcode Interface

Contained within IDE is a fully microcoded implementation of the Pep/9 and Pep/10 virtual machines. These extensions to their respective textbooks is dubbed PepMicro PepMicro adds a control section, missing in Pep9CPU, and extends the microcode language to allow conditional microcode branches. It integrates all the programming features of Pep/9 and the graphical CPU interaction of Pep9CPU to simulate the complete execution of assembly language programs.

• Extend the assembler and CPU simulator so that complete assembly language programs can be executed at the microcode level spanning four levels of system abstraction – the assembly level, the operating system level, the ISA level, and the microcode level.
• Runs both memory aligned and nonaligned programs. Assembly language programs that do not use optimal .ALIGN directives still execute correctly but slower.
• Provides performance statistics in the form of statement execution counts at the microcode level and the ISA level. Students can measure the performance differences between aligned and nonaligned programs.
• Retains the unit tests of the original Pep/9 CPU IDE so that students can write microcode fragments with the extended microinstruction format.
• Supports new debugging features like step-into, step-out, and step-over so students can trace assembly programs more efficiently.

Terminal Support

The IDE includes a command-line version of the Pep/9 and Pep/10 virtual machine.s It uses the assembler from the PepIDE application to create a .pepo file, and the simulator to execute the .pepo file.

Teachers can script PepTerm to batch test assembly language homework submissions.

Contributing

Please see our Contribution Guidelines before contributing to this project.

Debugging WASM

Install the following plugin into chrome. See Qt help for aditional settings