Merge branch 'main' into docs

README.md

@@ -31,7 +31,7 @@ You can use optional arguments to customize the output:
 
 # Examples
 
-Take a look at [examples](examples/README.md) for scheduling examples, and [API documentation](docs/API.md) for complete scheduling interface documentation.
+Take a look at [examples](examples/avx2_matmul/README.md) for scheduling examples, and [API documentation](docs/API.md) for scheduling interface documentation.
 
 
 # Build Exo from source
@@ -126,7 +126,7 @@ In this repository, folders are structured as follows:
     - **APIs.** Documentation for the APIs can be found in the [API documentation](docs/API.md).
       - `API.py` defines a stable API for top-level decorators (`proc`, `instr`, and `config`).
       - `API_scheduling.py` defines a API for scheduling primitives.
-      - `API_cursors.py` defines a API for scheduling primitives.  
+      - `API_cursors.py` defines a API for Cursors.
     - **Standard libraries.** These could be user-defined, but we provide them for convenience.
       - `libs/` contains some common memory definitions (`memories.py`) and custom malloc implementations. 
       - `platforms/` contains instruction definitions that are part of the release.
@@ -141,7 +141,7 @@ In this repository, folders are structured as follows:
 
 # Contact
 
-Please contact [[email protected]](mailto:[email protected]) if you have any questions.
+Please contact [[email protected]](mailto:[email protected]) or [[email protected]](mailto:[email protected]) if you have any questions.
 
 
 # Publication

dev-requirements.txt

@@ -1,9 +1,9 @@
-black==24.8.0
-coverage==7.6.1
-pre-commit==3.8.0
+black==24.10.0
+coverage==7.6.2
+pre-commit==4.0.1
 pytest-cov==5.0.0
 pytest-xdist==3.6.1
 pytest==8.3.3
 tox==4.21.2
-numpy==2.1.1
+numpy==2.1.2
 Pillow==10.4.0

examples/README.md → examples/avx2_matmul/README.md

@@ -6,7 +6,7 @@ This tutorial assumes some familiarity with SIMD instructions.
 Exo provides *scheduling operators* to transform program and rewrite them to make use of complex hardware instructions.
 We'll show you how to take a simple matrix multiplication kernel and transform it into an implementation that can make use of [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) vector instructions.
 
-The complete code with scheduling operations can be found in `exo/examples/x86_matmul.py`, and running `make` will compile the Exo code and generate an executable `avx2_matmul`.
+The complete code with scheduling operations can be found in `exo/examples/avx2_matmul/x86_matmul.py`, and running `make` will compile the Exo code and generate an executable `avx2_matmul`.
 
 ## Basic Implementation
 

examples/rvm_conv1d/.gitignore

@@ -0,0 +1 @@
+out/

examples/rvm_conv1d/Makefile

@@ -0,0 +1,31 @@
+PROG = conv1d
+OUT = out/
+CC = "${RISCV}/bin/clang"
+SPIKE = "${RISCV}/bin/spike"
+ASFLAGS = -march=rv32imc_xtheadmatrix0p1 -menable-experimental-extensions 
+CFLAGS = -O2 -g3 $(ASFLAGS) 
+
+default: sim
+exo_comp: exo/conv1d_exo.c
+
+$(OUT)/$(PROG).elf: $(OUT)/$(PROG).o $(OUT)/conv1d_exo.o
+	$(CC) $(LDFLAGS) -o $@ $^
+
+$(OUT)/$(PROG).o: main.c exo/conv1d_exo.h conv1Di32.h $(OUT) 
+	$(CC) $(CFLAGS) -o $@ -c $<
+
+$(OUT)/conv1d_exo.o: exo/conv1d_exo.c $(OUT)
+	$(CC) $(CFLAGS) -o $@ -c $<
+
+$(OUT):
+	@mkdir -p $(OUT)
+
+exo/conv1d_exo.h: exo/conv1d_exo.c
+exo/conv1d_exo.c: exo/conv1d.py
+	exocc -o exo/ --stem conv1d_exo exo/conv1d.py
+
+conv1Di32.h: gen_stimuli.py
+	python3 $<
+
+sim: $(OUT)/$(PROG).elf
+	@$(SPIKE) --isa=RV32IMC_xmatrix pk -s $<

examples/rvm_conv1d/README.md

@@ -0,0 +1,48 @@
+# Conv1D on RVM example
+
+This is an implementation of a simplified 1D convolution routine, using a custom [RISC-V ISA extension called RVM](https://github.com/esl-epfl/xheep_matrix_spec/tree/main).
+
+The tutorial accompanying this example is on [the main website](https://exo-lang.dev/tutorial.html). This page will just show you how to first compile the Exo program to C, and how to run it as well (optional.)
+
+## File organization
+
+* `main.c` - driver program testing handwritten vs Exo routine
+* `gen_stimuli.py` - generate C arrays used as test vectors for conv1d routine, with expected output
+* `conv1Di32.h` - generated output from `gen_stimuli.py`
+* `exo/conv1d.py` - Exo code for conv1d
+* `exo/conv1d_exo.{c,d,h}` - generated outputs from Exo
+
+
+## Setup Exo & Compile
+
+First follow [the documentation](https://github.com/exo-lang/exo#install-exo) to install Exo, if you have not already. We assume `exocc` is in `$PATH`, and you have `make` installed. To compile the exo program in `exo/conv1d.py`, run:
+
+```bash
+make exo_comp
+```
+
+The resulting C code for the example will be in `exo/conv1d_exo.c`.
+
+From here, if you would like to also compile the program to a RISC-V binary, and run it in a simulator, you will need the custom RVM toolchain. The following steps walk through that process. Otherwise, you can stop here.
+
+## Install RVM toolchain
+
+RVM is the custom RISC-V extension, which supports instructions and registers to do matrix operations. It requires a custom LLVM toolchain to build code, and in order to run programs, a fork of the Spike simulator. [The repo for RVM has a guide to set up these components](https://github.com/esl-epfl/xheep_matrix_spec/blob/main/BUILDING.md). In the end you should have the LLVM tools as well as Spike installed under `$RISCV/bin`.
+
+
+## Build
+
+Run `make` to build the driver program, and simulate it in spike. **This assumes you have `$RISCV` defined from the installation step.** You should see an output like this:
+
+```
+$ make
+...
+handwritten err: 0
+exo err: 0
+2350 ticks
+93797 cycles
+93799 instructions
+0.99 CPI
+```
+
+Note that the cycle counts are *not* accurate, and they should not be used to measure performance. Unfortunately, the hardware for RVM is not public as of today, and the Spike simulator is not meant to simulate these details, so it is only used for testing functional correctness.

examples/rvm_conv1d/conv1Di32.h

@@ -0,0 +1,20 @@
+#ifndef _CONV1Di32 
+#define _CONV1Di32 
+// This file is automatically generated
+int32_t __attribute__((section(".xheep_data_interleaved"))) DATA[] = {
+	0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
+
+int32_t __attribute__((section(".xheep_data_interleaved"))) KERNELS[] = {
+	0,1,2,3,10,11,12,13,20,21,22,23,30,31,32,33,100,101,102,103,110,111,112,113,120,121,122,123,130,131,132,133,200,201,202,203,210,211,212,213,220,221,222,223,230,231,232,233,300,301,302,303,310,311,312,313,320,321,322,323,330,331,332,333,400,401,402,403,410,411,412,413,420,421,422,423,430,431,432,433,500,501,502,503,510,511,512,513,520,521,522,523,530,531,532,533,600,601,602,603,610,611,612,613,620,621,622,623,630,631,632,633,700,701,702,703,710,711,712,713,720,721,722,723,730,731,732,733,
+	800,801,802,803,810,811,812,813,820,821,822,823,830,831,832,833,900,901,902,903,910,911,912,913,920,921,922,923,930,931,932,933,1000,1001,1002,1003,1010,1011,1012,1013,1020,1021,1022,1023,1030,1031,1032,1033,1100,1101,1102,1103,1110,1111,1112,1113,1120,1121,1122,1123,1130,1131,1132,1133,1200,1201,1202,1203,1210,1211,1212,1213,1220,1221,1222,1223,1230,1231,1232,1233,1300,1301,1302,1303,1310,1311,1312,1313,1320,1321,1322,1323,1330,1331,1332,1333,1400,1401,1402,1403,1410,1411,1412,1413,1420,1421,1422,1423,1430,1431,1432,1433,1500,1501,1502,1503,1510,1511,1512,1513,1520,1521,1522,1523,1530,1531,1532,1533};
+
+int32_t __attribute__((section(".xheep_data_interleaved"))) EXPECTED[] = {
+	416,680,944,1208,1472,1736,2000,2264,2528,2792,3056,3320,3584,2696,1800,900,2816,4680,6544,8408,10272,12136,14000,15864,17728,19592,21456,23320,25184,19496,13400,6900,5216,8680,12144,15608,19072,22536,26000,29464,32928,36392,39856,43320,46784,36296,25000,12900,7616,12680,17744,22808,27872,32936,38000,43064,48128,53192,58256,63320,68384,53096,36600,18900,10016,16680,23344,30008,36672,43336,50000,56664,63328,69992,76656,83320,89984,69896,48200,24900,12416,20680,28944,37208,45472,53736,62000,70264,78528,86792,95056,103320,111584,86696,59800,30900,14816,24680,34544,44408,54272,64136,74000,83864,93728,103592,113456,123320,133184,103496,71400,36900,17216,28680,40144,51608,63072,74536,86000,97464,108928,120392,131856,143320,154784,120296,83000,42900,
+	19616,32680,45744,58808,71872,84936,98000,111064,124128,137192,150256,163320,176384,137096,94600,48900,22016,36680,51344,66008,80672,95336,110000,124664,139328,153992,168656,183320,197984,153896,106200,54900,24416,40680,56944,73208,89472,105736,122000,138264,154528,170792,187056,203320,219584,170696,117800,60900,26816,44680,62544,80408,98272,116136,134000,151864,169728,187592,205456,223320,241184,187496,129400,66900,29216,48680,68144,87608,107072,126536,146000,165464,184928,204392,223856,243320,262784,204296,141000,72900,31616,52680,73744,94808,115872,136936,158000,179064,200128,221192,242256,263320,284384,221096,152600,78900,34016,56680,79344,102008,124672,147336,170000,192664,215328,237992,260656,283320,305984,237896,164200,84900,36416,60680,84944,109208,133472,157736,182000,206264,230528,254792,279056,303320,327584,254696,175800,90900};
+
+#define N 16
+#define IC 4
+#define W 4
+#define OC 16
+#define PAD 1
+#endif

examples/rvm_conv1d/exo/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+conv1d_exo.c
+conv1d_exo.h
+conv1d_exo.d