Update readme

Add workspace template

README.md

@@ -1,3 +1,5 @@
 # TGC Hammer
 
-This is TGC-Hammer, the HLS flow for custom ISA-Extensions.
+This is the base repo TGC-Hammer, the HLS flow for custom ISA-Extensions. It is used for building the toolflow executable, as well as the various tools (Longnail, SCAIE-V, ...).
+
+To use it, create a new workspace folder by calling the `init-workspace.sh` script from an empty folder. This will create the base workspace structure, including a README about usage details. The workspace will always use the executables from this repo, so if you rebuild them, the new ones will automatically be used.

init-workspace.sh

@@ -29,7 +29,7 @@ else
     echo "export TGC_HAMMER_WORKDIR=\"$PWD\"" >> source.sh
     echo "export PATH=\"${TGC_HAMMER_HOME}/toolflow/target/universal/stage/bin:$PATH\"" >> source.sh
 
-    echo "source source.sh" > .envrc
+    cp -r ${TGC_HAMMER_HOME}/* $PWD
 
     mkdir -p output
 fi

wsTemplate/.envrc

@@ -0,0 +1 @@
+source source.sh

wsTemplate/README.md

@@ -0,0 +1,32 @@
+# TGC Hammer Workspace
+
+This is a workspace for using the TGC Hammer toolchain for ISAX-HLS and integration into TGC cores.
+The required tools and executables are all located in the base TGC-Hammer repo from which this workspace was created.
+
+To use the toolchain just enter this directory, `direnv` will then automatically setup all required environment variables.
+Alternatively you can execute `source source.sh`.
+
+## Usage
+
+The executable for the toolchain is called `tgc-hammer`, it features various subcommands for different tasks.
+The two main ones `isaxHLS` and `isaxCore` are described in the sections below.
+
+It also features additionally subcommands for individual steps (e.g. just translate CoreDSL to MLIR), for more information see `tgc-hammer --help`.
+
+### isaxHLS
+
+This subcommand takes one or multiple input files describing the ISAXES and runs the Longnail HLS tool to create SystemVerilog respresentations for them.
+
+The base command looks like this: `tgc-hammer isaxHLS -c VexRiscv --useMinIISolution isax.core_desc`
+
+The `-c` or `--core` option is required, it provides Longnail with the Core Datasheet detailing core-specific scheduling information.
+
+Currently the `--useMinIISolution` option is also required, manually selecting scheduling solutions is WIP.
+
+The command ends with the input files. If multiple ones are specified, they are merged using Longnail before the scheduling and HLS. Both CoreDSL and already translated MLIR files are supported (also mixed).
+
+For additional options see `tgc-hammer isaxHLS --help`.
+
+### isaxCore
+
+WIP

wsTemplate/examples/LWC.core_desc

@@ -0,0 +1,79 @@
+
+InstructionSet Zxlwc_ascon {
+    architectural_state {
+        unsigned int XLEN=32;
+        register unsigned<XLEN> X[32] [[is_main_reg]];
+    }
+
+    functions {
+
+        unsigned<64> _ror64(unsigned<64> val, unsigned<64> shift_amount) {
+            return (val >> shift_amount) | (val << (64 - shift_amount));
+        }
+        // ROT_0 = { 19, 61,  1, 10,  7 }
+        unsigned<64> rot_0(unsigned<5> imm){
+            unsigned<64> ret;
+            if(imm == 0)
+                ret = 19;
+            else if(imm==1)
+                ret = 61;
+            else if(imm==2)
+                ret = 1;
+            else if(imm==3)
+                ret = 10;
+            else if(imm==4)
+                ret = 7;
+            else ret = 0;
+            return ret;
+        }
+        // ROT_1 = { 28, 39,  6, 17, 41 }
+        unsigned<64> rot_1(unsigned<5> imm){
+            unsigned<64> ret;
+            if(imm == 0)
+                ret =  28;
+            else if(imm==1)
+                ret =  39;
+            else if(imm==2)
+                ret =  6;
+            else if(imm==3)
+                ret =  17;
+            else if(imm==4)
+                ret =  41;
+            else ret = 0;
+            return ret;
+        }
+    }
+
+    instructions{
+        ASCON_SIGMA_LO [[enable=XLEN==32]] {
+            encoding: 2'b00 :: imm[4:0] :: rs2[4:0] :: rs1[4:0] :: 3'b111 :: rd[4:0] :: 7'b0101011;
+            behavior: {
+                        unsigned<32> x_hi = (unsigned<32>)X[rs2];
+                        unsigned<32> x_lo =  (unsigned<32>)X[rs1];
+                        unsigned<64> x = x_hi :: x_lo;
+                        unsigned<64> r = x ^ _ror64(x, rot_0(imm)) ^ _ror64(x, rot_1(imm));
+                        X[rd] = (unsigned<XLEN>)r[31:0];
+                    }
+
+        }
+        ASCON_SIGMA_HI [[enable=XLEN==32]] {
+            encoding: 2'b01 :: imm[4:0] :: rs2[4:0] :: rs1[4:0] :: 3'b111 :: rd[4:0] :: 7'b0101011;
+            behavior: {
+                        unsigned<32> x_hi =  (unsigned<32>)X[rs2];
+                        unsigned<32> x_lo =  (unsigned<32>)X[rs1];
+                        unsigned<64> x = x_hi :: x_lo;
+                        unsigned<64> r = x ^ _ror64(x, rot_0(imm)) ^ _ror64(x, rot_1(imm));
+                        X[rd] = (unsigned<XLEN>)r[63:32];
+                    }
+        }
+
+        ASCON_SIGMA [[enable=XLEN==64]] {
+            encoding: 2'b10 :: imm[4:0] :: 5'b00000 :: rs1[4:0] :: 3'b110 :: rd[4:0] :: 7'b0101011;
+            behavior: {
+                        unsigned<64> x = X[rs1];
+                        unsigned<64> r = x ^ _ror64(x, rot_0(imm)) ^ _ror64(x, rot_1(imm));
+                        X[rd] = (unsigned<XLEN>)r;
+                    }
+        }
+    }
+}