├── ROM Files ├── 7Seg.ROM ├── Fib.ROM └── BinaryToBCD.ROM ├── Info ├── CPU v1.0.pdf └── CPU Instructions.txt ├── LICENSE ├── Tools ├── genROM.py └── controlROM.py └── README.md /ROM Files/7Seg.ROM: -------------------------------------------------------------------------------- 1 | v2.0 raw 2 | 7E 30 6D 79 33 5B 5F 70 7F 7B -------------------------------------------------------------------------------- /ROM Files/Fib.ROM: -------------------------------------------------------------------------------- 1 | v2.0 raw 2 | 50 4d e0 51 4e e0 2d 70 3 | 4f 1e 4d 1f 64 4 | -------------------------------------------------------------------------------- /Info/CPU v1.0.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/eddiewastaken/logisim-discrete-CPU/HEAD/Info/CPU v1.0.pdf -------------------------------------------------------------------------------- /Info/CPU Instructions.txt: -------------------------------------------------------------------------------- 1 | Opcode Mnemonic Description 2 | ------ -------- ----------- 3 | 0000 NOP No operation 4 | 0001 LDA Load A reg with contents of given address 5 | 0010 ADD Add contents of given address to A reg 6 | 0011 SUB Subtract contents of given address from A reg 7 | 0100 STA Store contents of A reg at given address 8 | 0101 LDI Load A reg with given value 9 | 0110 JMP Jump to given address 10 | 0111 JC Jump to given address is Carry Flag is set 11 | 1000 JZ Jump to given address is Zero Flag is set 12 | 1001 N/A N/A 13 | 1010 N/A N/A 14 | 1011 N/A N/A 15 | 1100 N/A N/A 16 | 1101 N/A N/A 17 | 1110 OUT Load Out reg with contents of A reg 18 | 1111 HLT Halt the clock -------------------------------------------------------------------------------- /ROM Files/BinaryToBCD.ROM: -------------------------------------------------------------------------------- 1 | v2.0 raw 2 | 000 001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 038 039 040 041 042 043 044 045 046 047 048 049 050 051 052 053 054 055 056 057 058 059 060 061 062 063 064 065 066 067 068 069 070 071 072 073 074 075 076 077 078 079 080 081 082 083 084 085 086 087 088 089 090 091 092 093 094 095 096 097 098 099 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | This is free and unencumbered software released into the public domain. 2 | 3 | Anyone is free to copy, modify, publish, use, compile, sell, or 4 | distribute this software, either in source code form or as a compiled 5 | binary, for any purpose, commercial or non-commercial, and by any 6 | means. 7 | 8 | In jurisdictions that recognize copyright laws, the author or authors 9 | of this software dedicate any and all copyright interest in the 10 | software to the public domain. We make this dedication for the benefit 11 | of the public at large and to the detriment of our heirs and 12 | successors. We intend this dedication to be an overt act of 13 | relinquishment in perpetuity of all present and future rights to this 14 | software under copyright law. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 19 | IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 20 | OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 21 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 22 | OTHER DEALINGS IN THE SOFTWARE. 23 | 24 | For more information, please refer to 25 | -------------------------------------------------------------------------------- /Tools/genROM.py: -------------------------------------------------------------------------------- 1 | import csv, sys, os, argparse 2 | 3 | ###CLI Usage: python genROM.py "CSVFile.csv" "Address Width" "Data Width" 4 | 5 | def createParser(): 6 | parser = argparse.ArgumentParser(description='Generates a Logisim ROM file given a CSV of desired memory contents.') 7 | parser.add_argument('CSV', help='Path to input CSV file (without headers)') 8 | parser.add_argument('ADDR', help='Amount of ROM address lines (note - not total cells)', type=int) 9 | parser.add_argument('WIDTH', help='Bit width of each ROM cell', type=int) 10 | return parser 11 | 12 | def readCSV(path): 13 | datafile = open(path, 'r') 14 | datareader = csv.reader(datafile, delimiter=',') 15 | data = [] 16 | for row in datareader: 17 | data.append(row) 18 | return data 19 | 20 | def ceil(a, b): 21 | return -(-a // b) 22 | 23 | def toHex(array, addr, width): 24 | hexArray = [[('%0*X' % (ceil(width,4), int(i, base=2))) for i in j] for j in array] 25 | addresses = (2**addr) 26 | csvSize = sum(len(row) for row in hexArray) 27 | if csvSize > addresses: 28 | print("\n") 29 | print("Error - too many cells in CSV to fit in ROM!") 30 | print("Available ROM locations: " + str(addresses)) 31 | print("Supplied cells: " + str(csvSize)) 32 | print("Please edit, then run me again!") 33 | print("\n") 34 | exit() 35 | rows = len(array) 36 | cols = len(array[0]) 37 | for i in range(0, rows): 38 | for j in range(0, cols): 39 | #Checks width of data in each CSV cell 40 | actualWidth = len(str(bin(int(hexArray[i][j], base=16)))[2:]) 41 | if actualWidth > width: 42 | print("\n") 43 | print("Error - value in cell too large for ROM's bit width!") 44 | print("Problem value: " + str(bin(int(hexArray[i][j], base=16)))[2:] + " at cell (" + str(i) + ", " + str(j) + ")") 45 | print("Please edit, then run me again!") 46 | print("\n") 47 | exit() 48 | return hexArray 49 | 50 | def confirm(addr, width): 51 | response = "" 52 | addresses = (2**addr) 53 | print("\n") 54 | print("Writing for a ROM of " + str(addresses) + " locations * " + str(width) + " bit values.") 55 | print("\n") 56 | while response != "Y" and response != "N": 57 | response = input("Correct? Enter Y to proceed, or N to exit: ") 58 | return response 59 | 60 | #def toBin(array): 61 | # return [[(format(i, "016b")) for i in j] for j in array] 62 | 63 | def toFile(array): 64 | with open("out.ROM", mode='w', encoding='utf-8') as out: 65 | #Write headers for Logisim ROM file 66 | out.write("v2.0 raw") 67 | out.write("\n") 68 | #Write hex values to file, seperated by whitespace 69 | rows = len(array) 70 | cols = len(array[0]) 71 | for i in range(0, rows): 72 | for j in range(0, cols): 73 | val = array[i][j] 74 | out.write(val) 75 | out.write(' ') 76 | #Close file 77 | out.close() 78 | print("\n") 79 | print("ROM file successfully created!") 80 | print("\n") 81 | 82 | if __name__ == "__main__": 83 | argParser = createParser() 84 | args = argParser.parse_args(sys.argv[1:]) 85 | proceed = confirm(args.ADDR,args.WIDTH) 86 | if proceed == "N": 87 | print("\n") 88 | exit() 89 | else: 90 | exists = os.path.exists(args.CSV) 91 | if exists: 92 | toFile(toHex(readCSV(args.CSV), args.ADDR, args.WIDTH)) 93 | else: 94 | print("\n") 95 | print("Error - supplied CSV path doesn't exist!") 96 | print("\n") 97 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # logisim-discrete-CPU 2 | 3 | ![The CPU](https://i.imgur.com/aIL39s7.png) 4 | 5 | This project aims to mimic [Ben Eater's 8-Bit CPU Project](https://eater.net/8bit), in the Digital Logic Simulator Logisim Evolution. 6 | 7 | **Note:** *This project was developed in [Logisim Evolution v2.14.6](https://github.com/logisim-evolution/logisim-evolution/releases/tag/v2.14.6), and has only been tested on that version. Any other versions may break the project due to missing or differently sized circuit components.* 8 | 9 | A full writeup/guide to replicate this project yourself from scratch may be found in the `CPU v1.XX.pdf` file in the root of this repository. 10 | 11 | As Logisim doesn't support [VHDL](https://en.wikipedia.org/wiki/VHDL) modelling of components, each individual component and IC used by Ben has been built purely from discrete logic using Logisim's inbuilt logic gates, tri-state buffers, inputs and outputs. 12 | 13 | The discrete implementations have been carefully designed to mirror the near exact operation of the corresponding ICs, to allow physical breadboarding and construction if desired. Most are based on the 7400 Series, as used by Ben. The `CPU.circ` file is intended to be loaded by [Logisim Evolution](https://github.com/reds-heig/logisim-evolution), as it uses push buttons and a couple of other features not found in the original Logisim program. 14 | 15 | The pseudo-[28C16](http://cva.stanford.edu/classes/cs99s/datasheets/at28c16.pdf) (2K x 8-Bit ROM) used for the control logic (and output register display driver) is an exception to the discrete logic designs, due to its size. **Note** - The Control Logic ROM is pre-loaded with the correct microinstructions for the CPU, which mirrors the list of Ben Eater's (and uses the same microinstructions to achieve them). These are provided in `CPU Instructions.txt`. Logisim's ROM component is used instead, which is handy in allowing the loading of ROM image files. 16 | 17 | To that end, a Python 3 'helper' program was written to allow a CSV file of sequential binary instructions to be parsed and converted into a Logisim ROM image file, to be loaded into a ROM component for fast programming of the discrete RAM. This makes writing programs for the CPU much quicker. The utility is named genROM and is run from the command line with the following usage: 18 | 19 | `> python genROM.py CSV ADDR WIDTH` 20 | 21 | Where: 22 | 23 | `CSV = Path to input CSV file (without any headers)` 24 | `ADDR = Amount of ROM address lines (note - not total cells)` 25 | `WIDTH = Bit width of each ROM cell` 26 | 27 | The ADDR and WIDTH arguments are variable, in the case that the system is extended beyond the scope of this project and the available memory increased. The CSV content passed to the utility should simply look like this example: 28 | 29 | `10010001, 11100001, 11011001, 00110111...` 30 | 31 | Each representing a full instruction (opcode & operand) in binary. If too many values are supplied for the given ROM dimensions, or a value too large is supplied, the error will be caught and the user notified. 32 | 33 | Once produced, the ROM image file can be loaded into the 'RAM Programmer' subcircuit by right clicking on the ROM component, and choosing `Load Image...`: 34 | 35 | ![Loading the ROM](https://i.imgur.com/AEo5FPI.png) 36 | 37 | Then, inside the main CPU circuit (after pulsing the `RESET` input, which needs to be done every time the CPU simulation is reset to initialise the internal registers), the `PROG_RAM` input can be activated, and the `COMMIT` and `STEP` push buttons can be toggled sequentially to `COMMIT` each instruction to the RAM's memory, and `STEP` to the next address in the ROM Programmer's (and RAM's) memory ready to repeat: 38 | 39 | ![Loading the RAM](https://i.imgur.com/vtcvBFd.png) 40 | 41 | This can be repeated until all desired RAM locations are filled with instructions. When done, simply the `PROG_RAM` input can be returned to 0, `RESET` may be used again to reset the Program Counter to 0 (if not already there), and the Clock either manually stepped, or automatic Clock ticks enabled from the 'Simulate' Menu: 42 | 43 | ![Activating automatic Clock ticks](https://i.imgur.com/7l080oo.png) 44 | 45 | 'Tick Frequency' can also be altered, results may vary depending on your machine. Included in this project is a demo ROM image file, `Fib.ROM`, which computes the Fibonacci sequence from 0 to 233, then loops. `7Seg.ROM` and `BinaryToBCD.ROM` files are also included, which are pre-loaded into the ROMs used as the output display drivers. `controlROM.py` will generate the required control ROM file based on the microinstructions given within. 46 | 47 | ## Aims 48 | 49 | The idea of this project is to present a full guide to build up to this project yourself, starting with only basic digital logic circuit knowledge. Please log any issues, and let me know if you'd like to use this project and/or build manual for anything cool! Forks are welcomed to build on and expand this system to bigger and better things, but it's encouraged to use as much discrete logic as possible! 50 | 51 | # Todo 52 | 53 | - Fix `HLT` microinstruction, as Logisim currently doesn't play nice with it 54 | - Implement an optional Clock cycle saving subcircuit to skip to the Instruction if the current control word == 0 55 | - Split the subcircuits into a Logisim library to be loaded inside other Logisim circuits 56 | -------------------------------------------------------------------------------- /Tools/controlROM.py: -------------------------------------------------------------------------------- 1 | #Define microinstruction values 2 | micro = { 3 | "HLT" : "0b1000000000000000", #Halt clock 4 | "MI" : "0b0100000000000000", #Memory address register in 5 | "RI" : "0b0010000000000000", #RAM data in 6 | "RO" : "0b0001000000000000", #RAM data out 7 | "IO" : "0b0000100000000000", #Instruction register out 8 | "II" : "0b0000010000000000", #Instruction register in 9 | "AI" : "0b0000001000000000", #A register in 10 | "AO" : "0b0000000100000000", #A register out 11 | "EO" : "0b0000000010000000", #ALU out 12 | "SU" : "0b0000000001000000", #ALU subtract 13 | "BI" : "0b0000000000100000", #B register in 14 | "OI" : "0b0000000000010000", #Output register in 15 | "CE" : "0b0000000000001000", #Program counter enable 16 | "CO" : "0b0000000000000100", #Program counter out 17 | "J" : "0b0000000000000010", #Jump (program counter in) 18 | "FI" : "0b0000000000000001" #Flag register in 19 | } 20 | 21 | #2D array of opcodes and microinstructions in each 22 | ops = [ 23 | ["MI|CO", "RO|II|CE", "0", "0", "0", "0", "0", "0"], #0000 - NOP (No operation) 24 | ["MI|CO", "RO|II|CE", "IO|MI", "RO|AI", "0", "0", "0", "0"], #0001 - LDA (Load A reg with contents of given address) 25 | ["MI|CO", "RO|II|CE", "IO|MI", "RO|BI", "EO|AI|FI", "0", "0", "0"], #0010 - ADD (Add contents of given address to A reg) 26 | ["MI|CO", "RO|II|CE", "IO|MI", "RO|BI", "EO|AI|SU|FI", "0", "0", "0"], #0011 - SUB (Subtract contents of given address from A reg) 27 | ["MI|CO", "RO|II|CE", "IO|MI", "AO|RI", "0", "0", "0", "0"], #0100 - STA (Store contents of A reg at given address) 28 | ["MI|CO", "RO|II|CE", "IO|AI", "0", "0", "0", "0", "0"], #0101 - LDI (Load A reg with given value) 29 | ["MI|CO", "RO|II|CE", "IO|J", "0", "0", "0", "0", "0"], #0110 - JMP (Jump to given address) 30 | ["MI|CO", "RO|II|CE", "0", "0", "0", "0", "0", "0"], #0111 - JC (Jump to given address if carry flag is set) 31 | ["MI|CO", "RO|II|CE", "0", "0", "0", "0", "0", "0"], #1000 - JZ (Jump to given address if zero flag is set) 32 | ["MI|CO", "RO|II|CE", "0", "0", "0", "0", "0", "0"], #1001 33 | ["MI|CO", "RO|II|CE", "0", "0", "0", "0", "0", "0"], #1010 34 | ["MI|CO", "RO|II|CE", "0", "0", "0", "0", "0", "0"], #1011 35 | ["MI|CO", "RO|II|CE", "0", "0", "0", "0", "0", "0"], #1100 36 | ["MI|CO", "RO|II|CE", "0", "0", "0", "0", "0", "0"], #1101 37 | ["MI|CO", "RO|II|CE", "AO|OI", "0", "0", "0", "0", "0"], #1110 - OUT (Load Out reg with contents of A reg) 38 | ["MI|CO", "RO|II|CE", "HLT", "0", "0", "0", "0", "0"] #1111 - HLT (Halt the clock) 39 | ] 40 | 41 | JMP = ["MI|CO", "RO|II|CE", "IO|J", "0", "0", "0", "0", "0"] 42 | 43 | #Parse each opcode step into int values 44 | def parseExp(exp): 45 | #Replace microcode label(s) with binary value(s) 46 | for code, val in micro.items(): 47 | exp = exp.replace(code, val) 48 | #Evaluate bitwise operation expression as int 49 | return eval(exp) 50 | 51 | #Parse entire 2d array, return 2d array of same dimensions containing computed values 52 | def parse2D(array): 53 | #Create result array 54 | rows = len(array) 55 | cols = len(array[0]) 56 | result = [[0 for x in range(cols)] for y in range(rows)] 57 | #Map function 58 | for i in range(0, rows): 59 | for j in range(0, cols): 60 | result[i][j] = parseExp(array[i][j]) 61 | return result 62 | 63 | def toHex(array): 64 | return [[("%0.4x" % i) for i in j] for j in array] 65 | 66 | def toBin(array): 67 | return [[(format(i, "016b")) for i in j] for j in array] 68 | 69 | def toFiles(array, header): 70 | with open("ROM_LOW_FLAGS.ROM", mode='a', encoding='utf-8') as rL, open("ROM_HIGH_FLAGS.ROM", mode='a', encoding='utf-8') as rH: 71 | if header: 72 | #Write headers for Logisim ROM file 73 | rL.write("v2.0 raw") 74 | rL.write("\n") 75 | rH.write("v2.0 raw") 76 | rH.write("\n") 77 | #Write upper and lower bytes of hex values to each file, seperated by whitespace 78 | rows = len(array) 79 | cols = len(array[0]) 80 | for i in range(0, rows): 81 | for j in range(0, cols): 82 | val = array[i][j] 83 | rL.write(val[2:]) 84 | rL.write(' ') 85 | rH.write(val[:2]) 86 | rH.write(' ') 87 | #Close files 88 | rL.close() 89 | rH.close() 90 | 91 | #Neither 92 | out = parse2D(ops) 93 | outBin = toBin(out) 94 | outHex = toHex(out) 95 | toFiles(outHex, True) 96 | 97 | #JC 98 | JC = ops.copy() 99 | JC[7] = JMP 100 | out = parse2D(JC) 101 | outBin = toBin(out) 102 | outHex = toHex(out) 103 | toFiles(outHex, False) 104 | 105 | #JZ 106 | JZ = ops.copy() 107 | JZ[8] = JMP 108 | out = parse2D(JZ) 109 | outBin = toBin(out) 110 | outHex = toHex(out) 111 | toFiles(outHex, False) 112 | 113 | #Both 114 | BOTH = ops.copy() 115 | BOTH[7] = JMP 116 | BOTH[8] = JMP 117 | 118 | #Main 119 | out = parse2D(BOTH) 120 | outBin = toBin(out) 121 | outHex = toHex(out) 122 | toFiles(outHex, False) --------------------------------------------------------------------------------