{"id":15451434,"url":"https://github.com/davidar/subleq","last_synced_at":"2026-03-02T03:36:46.401Z","repository":{"id":659790,"uuid":"302651","full_name":"davidar/subleq","owner":"davidar","description":"CPU design and toolchain for a simple computer architecture","archived":false,"fork":false,"pushed_at":"2015-06-09T07:08:49.000Z","size":367,"stargazers_count":125,"open_issues_count":0,"forks_count":15,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-10-19T07:34:52.636Z","etag":null,"topics":["cpu","subleq"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidar.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-09-10T01:59:16.000Z","updated_at":"2025-10-15T10:32:38.000Z","dependencies_parsed_at":"2022-08-16T10:35:20.752Z","dependency_job_id":null,"html_url":"https://github.com/davidar/subleq","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/davidar/subleq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidar%2Fsubleq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidar%2Fsubleq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidar%2Fsubleq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidar%2Fsubleq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidar","download_url":"https://codeload.github.com/davidar/subleq/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidar%2Fsubleq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29991932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpu","subleq"],"created_at":"2024-10-01T21:24:46.511Z","updated_at":"2026-03-02T03:36:46.386Z","avatar_url":"https://github.com/davidar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Project homepage: \u003chttp://da.vidr.cc/projects/subleq/\u003e\n\nSUBLEQ (SUbtract and Branch if Less than or EQual to zero) is a type of\nOISC (One Instruction Set Computer) / URISC (Ultimate Reduced Instruction Set\nComputer) architecture. It has only one instruction of the form:\n    A B C\nThis is equivalent to the following pseudocode:\n    mem[B] = mem[B] - mem[A]\n    if mem[B] \u003c= 0 then goto C\nCompound instructions, such as addition, can be formed from sequences of these\nsimple SUBLEQ instructions. For examples of these, see the src/*.asq source\nfiles - most compound instructions include a comment about their function.\nIndirect addressing (pointers) can be emulated through self-modifying code,\nwhere operations are performed on the instructions themselves.\nSee [1,2,3,4,6] for further information.\n\nThis project consists of four main parts:\n- a CPU capable of executing SUBLEQ instructions\n- libraries for programs written in SUBLEQ assembly, and a demo program to\n  demonstrate these\n- a minimal SUBLEQ interpreter (with I/O) written in C\n- JSubleq: a SUBLEQ interpreter written in JavaScript\n\nCPU\nSchematics for a SUBLEQ-based CPU are provided in the logisim/ directory. A\nrecent version of Logisim[5] is required to simulate the CPU. Simulation\ninstructions are provided below under the SIMULATION heading.\n\nThere are three main buses in the CPU:\n- A bus: contains the address of the current memory location\n- B bus: contains the output of the ALU\n- D bus: contains the data read from memory\n\nThe CPU has six control signals:\n- MAR: the Memory Address Register should be updated with the value of the\n       D bus at the end of this cycle\n- PC:  the Program Counter should be updated at the end of this cycle\n- JMP: the PC should be loaded with the value of the D bus at the end of this\n       cycle if the LEQ flag has been set by the ALU, otherwise PC is just\n       incremented if either JMP or LEQ are false\n- RD:  the value of MAR should be loaded onto the A bus, otherwise it is loaded\n       with the value of PC if RD is false\n- WR:  the value of the B bus should be stored to memory at the end of this\n       cycle, and the value of the LEQ flag should be updated\n- A:   signals that the \"A\" operand is currently on the D bus, so the A\n       register should be updated at the end of this cycle\n\nThese signals are controlled by a 5-microinstruction microprogram which runs in\na continous loop. The signals enabled by each of these microinstructions are:\n0) MAR, PC: load mem[PC] (address of A operand) into MAR, increment PC\n1) RD, A:   load mem[MAR] into the A register\n2) MAR, PC: load mem[PC] (address of B operand) into MAR, increment PC\n3) RD, WR:  load mem[MAR] onto the D bus, then write the value of the B bus\n            (equal to the value of the D bus minus the value of the A register)\n            into mem[MAR]\n4) PC, JMP: if the LEQ flag is set (the result of B-A was less than or equal to\n            zero) then set PC to mem[PC] (the C operand) i.e. jump to C,\n            otherwise increment PC\n\nInput/output is performed through memory-mapped I/O, with the I/O driver mapped\nto address 0xffffffff (-1). If the A signal is enabled, then reading from this\naddress returns the negation of the next input character. If the A signal is\nnot enabled, then the value 0xffffffff is returned. Writing to this address\nprints the character obtained by performing a bitwise NOT on the value of the B\nbus. This behaviour allows the following I/O instructions to be performed:\n- (-1) X: add the input character to X (X -= -input)\n- X (-1): output the character in X (subtracting X from 0xffffffff gives NOT X,\n          then performing a NOT on this yields the original X)\n\nJumping to address 0xffffffff (-1) disables the clock signal, effectively\nhalting the CPU.\n\nSIMULATION\nTo simulate the CPU:\n1) open logisim/cpu.circ in Logisim[5]\n2) increase the simulation speed: Simulate \u003e Tick Frequency \u003e 1024 Hz\n3) load a program: to run the demo program, first make sure you have run `make`\n   in the project root directory, then\n   right-click the component labeled \"RAM\" \u003e Load Image... \u003e ../image.hex\n4) start the simulation: Simulate \u003e Ticks Enabled\n5) make sure you're using the hand tool, and select the component labeled\n   \"Input\" by clicking on it\n6) interact with the program as you would with any other console-based\n   application\n7) if the clock line turns blue, it means that the program has halted\n8) to stop the machine, uncheck Simulate \u003e Ticks Enabled, then press the reset\n   button labeled \"R\"\n9) repeat from step 3 if necessary\n\nLIBRARIES/DEMO\nLibraries for programs written in SUBLEQ assembly, as accepted by sqasm[6], are\navailable in the src/ directory.\n\nThey provide several common functions:\n- getint (read integer from input)\n- gets (read string from input)\n- putint (write integer to output)\n- puts (write string to output)\n\nSeveral useful procedures are also available:\n- bubblesort (sort a string of characters)\n- calc (perform a given operation on two integers)\n- factorial (calculate the factorial of a positive integer)\n- primes (generate and print a list of primes)\n\nVarious useful constants and scratch variables are provided by ascii.asq,\nboot.asq and data.asq.\n\nUsage information and equivalent C code (where appropriate) is provided in the\ncomments of each of these files.\n\nsrc/menu.asq contains a menu-driven program demonstrating the above libraries.\nSimply call `make run` in the project root directory to run the demo program.\n\nINTERPRETER\nA very minimal (only 222 bytes in size) SUBLEQ interpreter (sq.c) written in C\nis available in the src/ directory. It has been somewhat obfuscated to reduce\nthe code size, so a more readable version is also provided (src/sq.orig.c).\n\nIt should function similarly to sqrun[6]. See the comment at the top of\nsrc/sq.orig.c for usage information.\n\nJSUBLEQ\nThe JSubleq interpreter can be used by navigating a web browser to\njsubleq/jsubleq.html\n\n[1] http://en.wikipedia.org/wiki/Subleq\n[2] http://esolangs.org/wiki/Subleq\n[3] http://techtinkering.com/articles/?id=20\n[4] http://ece.ucsb.edu/~parhami/pubs_folder/parh88-ijeee-ultimate-risc.pdf\n[5] http://cburch.com/logisim/\n[6] http://mazonka.com/subleq/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidar%2Fsubleq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidar%2Fsubleq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidar%2Fsubleq/lists"}