initial commit

Author: sameer

.gitignore

@@ -0,0 +1,41 @@
+.vscode
+.venv
+*.pin
+*.pof
+*.sof
+*.qpf
+*.qsf
+*.sid
+*.map.*
+*.sta.*
+*.fit.*
+bitstream.tcl
+bitstream
+incremental_db
+*.hdb
+*.cdb
+*.ddb
+*.idb
+*.rdb
+*.logdb
+*.qmsg
+*.hsd
+*.ammdb
+db
+*.rpt
+*.sld
+*.jdi
+*.done
+*.pow.*
+Makefile
+project
+project.tcl
+files.tcl
+*.vcd
+*.vvp
+run.command
+modelsim.ini
+transcript
+work/
+*.wlf
+ip_cores/

.travis.yml

@@ -0,0 +1,29 @@
+sudo: required
+language: python
+os: linux
+addons:
+  apt:
+    update: false
+    packages:
+      - lib32z1
+      - lib32stdc++6
+      - libexpat1:i386
+      - libc6:i386
+      - libsm6:i386
+      - libncurses5:i386
+      - libx11-6:i386
+      - zlib1g:i386
+      - libxext6:i386
+      - libxft2:i386
+
+install:
+    - pip install -r requirements.txt
+    - stat /home/travis/intelFPGA/19.1/modelsim_ase || (curl 'http://download.altera.com/akdlm/software/acdsinst/19.1std/670/ib_installers/ModelSimSetup-19.1.0.670-linux.run' -o ModelSimSetup.run && chmod +x ModelSimSetup.run && travis_wait 30 ./ModelSimSetup.run --mode unattended --accept_eula 1 && sed -i 's/linux_rh60/linux/g' /home/travis/intelFPGA/19.1/modelsim_ase/vco )
+script:
+    - export PATH=$PATH:/home/travis/intelFPGA/19.1/modelsim_ase/bin
+    - cd ./sim/xorshift_tb/ && hdlmake fetch && hdlmake && make
+    - cd -
+
+cache:
+    directories:
+        - /home/travis/intelFPGA/

LICENSE-APACHE

@@ -0,0 +1,13 @@
+Copyright 2020 Sameer Puri
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Sameer Puri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Manifest.py

@@ -0,0 +1,3 @@
+modules = {
+    "local": "./src/"
+}

README.md

@@ -0,0 +1,26 @@
+# rand
+
+[![Build Status](https://travis-ci.com/hdl-util/rand.svg?branch=master)](https://travis-ci.com/hdl-util/rand)
+
+SystemVerilog code for arbitrary width random number utilities.
+
+## Why?
+
+I needed an efficient, easy way to generate gray codes for dual clock FIFOs. It's a pain to manually write out a gray code. Why not let a module do the heavy lifting for you?
+
+## Usage
+
+### LFSR
+
+1. Take files from `src/` and add them to your own project. If you use [hdlmake](https://hdlmake.readthedocs.io/en/master/), you can add this repository itself as a remote module.
+1. Other helpful modules are also available in this GitHub organization.
+1. Consult the testbench in `test/xorshift_tb.sv` for example usage.
+1. Read through the parameter descriptions in `xorshift.sv` and tailor any instantiations to your situation.
+1. Please create an issue if you run into a problem or have any questions.
+
+## To-do List
+
+* [x] [Xorshift](https://en.wikipedia.org/wiki/Xorshift) (LFSR)
+* [ ] [CBRNG](https://en.wikipedia.org/wiki/Counter-based_random_number_generator_(CBRNG)#Squares_RNG)
+  * Making Squares RNG arbitrary width seems non-trivial, unfortunately
+* More upon request

requirements.txt

@@ -0,0 +1 @@
+hdlmake==3.3

sim/vsim.do

@@ -0,0 +1 @@
+run -all;

sim/xorshift_tb/Manifest.py

@@ -0,0 +1,9 @@
+action = "simulation"
+sim_tool = "modelsim"
+sim_top = "xorshift_tb"
+
+sim_post_cmd = "vsim -novopt -do ../vsim.do -c xorshift_tb"
+
+modules = {
+  "local" : [ "../../test/" ],
+}

src/Manifest.py

@@ -0,0 +1,3 @@
+files = [
+    "xorshift.sv"
+]

src/xorshift.sv

@@ -0,0 +1,106 @@
+module xorshift #(
+    parameter int WIDTH,
+    // By default, a polynomial from a table of known polynomials is picked.
+    // You may want to specify your own if your polynomial is beyond the supported range
+    parameter bit [WIDTH-1:0] POLYNOMIAL = WIDTH'(0)
+) (
+    input logic clk,
+    input logic reset,
+    input logic [WIDTH-1:0] seed,
+    output logic [WIDTH-1:0] state
+);
+
+logic [WIDTH-1:0] polynomial;
+logic lfsr_xnor;
+
+integer i;
+always_comb
+begin
+    lfsr_xnor = 1'b0;
+    for (i = 0; i < WIDTH; i++)
+    begin
+        if (polynomial[i])
+            lfsr_xnor = lfsr_xnor ^~ state[i];
+    end
+end
+
+always_ff @(posedge clk)
+begin
+    if (reset)
+        state <= seed;
+    else
+        state <= {state[WIDTH-2:0], lfsr_xnor};
+end
+
+generate
+    if (POLYNOMIAL != WIDTH'(0))
+        assign polynomial = POLYNOMIAL;
+    else
+        case (WIDTH)
+// Special thanks to Philip Koopman for these maximal length LFSR feedback polynomials
+// for i in {4..64}; do echo -n $i': assign polynomial = '$i"'"'h'; curl 'http://users.ece.cmu.edu/~koopman/lfsr/'$i'.txt' 2>/dev/null | head -n 1 | tr -d '\n'; echo ';'; done
+4: assign polynomial = 4'h9;
+5: assign polynomial = 5'h12;
+6: assign polynomial = 6'h21;
+7: assign polynomial = 7'h41;
+8: assign polynomial = 8'h8E;
+9: assign polynomial = 9'h108;
+10: assign polynomial = 10'h204;
+11: assign polynomial = 11'h402;
+12: assign polynomial = 12'h829;
+13: assign polynomial = 13'h100D;
+14: assign polynomial = 14'h2015;
+15: assign polynomial = 15'h4001;
+16: assign polynomial = 16'h8016;
+17: assign polynomial = 17'h10004;
+18: assign polynomial = 18'h20013;
+19: assign polynomial = 19'h40013;
+20: assign polynomial = 20'h80004;
+21: assign polynomial = 21'h100002;
+22: assign polynomial = 22'h200001;
+23: assign polynomial = 23'h400010;
+24: assign polynomial = 24'h80000D;
+25: assign polynomial = 25'h1000004;
+26: assign polynomial = 26'h2000023;
+27: assign polynomial = 27'h4000013;
+28: assign polynomial = 28'h8000004;
+29: assign polynomial = 29'h10000002;
+30: assign polynomial = 30'h20000029;
+31: assign polynomial = 31'h40000004;
+32: assign polynomial = 32'h80000057;
+33: assign polynomial = 33'h100000029;
+34: assign polynomial = 34'h200000073;
+35: assign polynomial = 35'h400000002;
+36: assign polynomial = 36'h80000003B;
+37: assign polynomial = 37'h100000001F;
+38: assign polynomial = 38'h2000000031;
+39: assign polynomial = 39'h4000000008;
+40: assign polynomial = 40'h800000001C;
+41: assign polynomial = 41'h10000000004;
+42: assign polynomial = 42'h2000000001F;
+43: assign polynomial = 43'h4000000002C;
+44: assign polynomial = 44'h80000000032;
+45: assign polynomial = 45'h10000000000D;
+46: assign polynomial = 46'h200000000097;
+47: assign polynomial = 47'h400000000010;
+48: assign polynomial = 48'h80000000005B;
+49: assign polynomial = 49'h1000000000038;
+50: assign polynomial = 50'h200000000000E;
+51: assign polynomial = 51'h4000000000025;
+52: assign polynomial = 52'h8000000000004;
+53: assign polynomial = 53'h10000000000023;
+54: assign polynomial = 54'h2000000000003E;
+55: assign polynomial = 55'h40000000000023;
+56: assign polynomial = 56'h8000000000004A;
+57: assign polynomial = 57'h100000000000016;
+58: assign polynomial = 58'h200000000000031;
+59: assign polynomial = 59'h40000000000003D;
+60: assign polynomial = 60'h800000000000001;
+61: assign polynomial = 61'h1000000000000013;
+62: assign polynomial = 62'h2000000000000034;
+63: assign polynomial = 63'h4000000000000001;
+64: assign polynomial = 64'h800000000000000D;
+        endcase
+endgenerate
+
+endmodule

test/Manifest.py

@@ -0,0 +1,7 @@
+files = [
+    "xorshift_tb.sv"
+]
+
+modules = {
+  "local" : [ "../src/" ],
+}

test/xorshift_tb.sv

@@ -0,0 +1,33 @@
+module xorshift_tb;
+    timeunit 1ns;
+    timeprecision 1ns;
+    logic clk = 1'b0;
+    always
+    begin
+        #1;
+        clk <= ~clk;
+    end
+    localparam int WIDTH = 12;
+    logic reset = 1'b1;
+    logic [WIDTH-1:0] seed = WIDTH'(1), state;
+    xorshift #(.WIDTH(WIDTH)) xorshift(.clk(clk), .reset(reset), .seed(seed), .state(state));
+
+    logic [WIDTH-1:0] seen [0:2**WIDTH-1];
+    integer i, current = -1;
+    always_ff @(posedge clk)
+    begin
+        if (current == -1)
+            reset <= 1'b0;
+        else if (current == 2**WIDTH - 1)
+            $finish;
+        else
+        begin
+            seen[current] <= state;
+            for (i = 0; i < current; i++)
+            begin
+                assert(seen[i] != state) else $fatal(1, "Encountered a repeat of %d at %d %d", state, i, current);
+            end
+        end
+        current <= current + 1'd1;
+    end
+endmodule