From f7e7c4103468166fe52173e087984aa9e9dbf86b Mon Sep 17 00:00:00 2001 From: Emilien Bauer Date: Fri, 20 Jan 2023 14:13:53 +0000 Subject: [PATCH] Deploy RiscEmu in a JupyterLite distribution. (#18) * Try and deploy a RiscEmu JupyterLite distribution. * Add examples to the JupyterLite deployment. * Add some demo notebooks and link to it in Readme. Co-authored-by: Emilien Bauer --- .github/workflows/jupyterlite.yml | 100 ++++++++++++++++++++++++++++++ README.md | 2 + docs/PythonDemo.ipynb | 53 ++++++++++++++++ examples/fibs.asm | 4 +- 4 files changed, 156 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/jupyterlite.yml create mode 100644 docs/PythonDemo.ipynb diff --git a/.github/workflows/jupyterlite.yml b/.github/workflows/jupyterlite.yml new file mode 100644 index 0000000..421f48c --- /dev/null +++ b/.github/workflows/jupyterlite.yml @@ -0,0 +1,100 @@ +name: Deploy JupiterLite Page + +on: + # Trigger the workflow on push or pull request, + # but only for the master branch + push: + branches: + - master + pull_request: + branches: + - master + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout RiscEmu + uses: actions/checkout@v3 + with: + path: riscemu + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + + - name: Install dependencies + run: | + python -m pip install jupyterlite[all] libarchive-c build pyodide-build + + - name: Build RiscEmu source distribution + run: | + cd riscemu + python setup.py sdist + + # Pyodide is cached, so cloned only if not present in the cache, otherwise + # just checked out to whatever desired version and partially rebuilt. + + - name: Restore cached Pyodide tree + id: cache-pyodide + uses: actions/cache@v3 + with: + path: pyodide + key: pyodide + + - name: Clone pyodide if not cached + if: steps.cache-pyodide.outputs.cache-hit != 'true' + run: git clone https://github.com/pyodide/pyodide.git + + # Clean the xDSL and FrozenList package folders, generate their skeletons + # and do the necessary updates before building. + - name: Build custom Pyodide distribution + run: | + + cd pyodide + git fetch --all + git checkout 0.22.0a3 + python -m pip install -r requirements.txt + sudo apt update && sudo apt install f2c + + rm -rf packages/riscemu + pyodide skeleton pypi riscemu + + PYODIDE_PACKAGES="riscemu" make + + - name: Build the JupyterLite site + run: | + mkdir content + cp riscemu/docs/* content -r + cp riscemu/examples content -r + + rm -rf pyodide/pyodide + mkdir pyodide/pyodide + mv pyodide/dist pyodide/pyodide/pyodide + + python -m jupyter lite build --contents content --pyodide pyodide/pyodide + + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: ./_output + + deploy: + needs: build + if: github.ref == 'refs/heads/master' && github.event_name == 'push' + permissions: + pages: write + id-token: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 + + diff --git a/README.md b/README.md index a8b2b83..ac0bb5b 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,8 @@ Hello world Program exited with code 0 ``` +If you want to run it from a python script, here is [an online demo](https://AntonLydike.github.io/riscemu/lab/index.html?path=PythonDemo.ipynb). + The [`read` syscall](docs/syscalls.md) defaults to readline behaviour. Reading "true chunks" (ignoring newlines) is currently not supported. See the docs on [asembly](docs/assembly.md) for more detail on how to write assembly code for this emulator. diff --git a/docs/PythonDemo.ipynb b/docs/PythonDemo.ipynb new file mode 100644 index 0000000..ccaf9b1 --- /dev/null +++ b/docs/PythonDemo.ipynb @@ -0,0 +1,53 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Using RiscEmu from Python\n", + "\n", + "Here is how you can run some assembly through RiscEmu from Python.\n", + "\n", + "This example is using [this fibonacci assembly](examples/fibs.asm)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from riscemu import RunConfig, UserModeCPU, RV32I, RV32M, AssemblyFileLoader\n", + "\n", + "cfg = RunConfig(debug_instruction=False, verbosity=50)\n", + "cpu = UserModeCPU((RV32I, RV32M), cfg)\n", + "\n", + "loader = AssemblyFileLoader.instantiate('examples/fibs.asm', [])\n", + "cpu.load_program(loader.parse())\n", + "\n", + "cpu.launch(cpu.mmu.programs[-1], True)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.7" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/examples/fibs.asm b/examples/fibs.asm index 6038c17..48a46e5 100644 --- a/examples/fibs.asm +++ b/examples/fibs.asm @@ -10,7 +10,6 @@ main: addi s2, zero, 56 ; last storage index addi t0, zero, 1 ; t0 = F_{i} addi t1, zero, 1 ; t1 = F_{i+1} - ebreak ; launch debugger loop: sw t0, fibs(s1) ; save add t2, t1, t0 ; t2 = F_{i+2} @@ -19,7 +18,6 @@ loop: addi s1, s1, 4 ; increment storage pointer blt s1, s2, loop ; loop as long as we did not reach array length ; exit gracefully - ebreak ; launch debugger addi a0, zero, 0 addi a7, zero, 93 - scall ; exit with code 0 \ No newline at end of file + scall ; exit with code 0