{"id":21406007,"url":"https://github.com/jes/scamp-cpu","last_synced_at":"2025-10-28T16:45:53.706Z","repository":{"id":37491109,"uuid":"330752330","full_name":"jes/scamp-cpu","owner":"jes","description":"A homebrew 16-bit CPU with a homebrew Unix-like-ish operating system.","archived":false,"fork":false,"pushed_at":"2023-12-08T11:10:40.000Z","size":43930,"stargazers_count":286,"open_issues_count":0,"forks_count":7,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-06-05T01:33:16.975Z","etag":null,"topics":["16-bit","16-bit-cpu","cpu","electronics","hardware","verilog"],"latest_commit_sha":null,"homepage":"https://incoherency.co.uk/scamp/","language":"Slash","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-18T18:22:52.000Z","updated_at":"2025-05-21T21:26:08.000Z","dependencies_parsed_at":"2023-01-28T01:00:32.927Z","dependency_job_id":"380f4a70-4be8-4787-95dc-d65815bcc46b","html_url":"https://github.com/jes/scamp-cpu","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jes/scamp-cpu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jes%2Fscamp-cpu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jes%2Fscamp-cpu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jes%2Fscamp-cpu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jes%2Fscamp-cpu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jes","download_url":"https://codeload.github.com/jes/scamp-cpu/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jes%2Fscamp-cpu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281476640,"owners_count":26508143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","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":["16-bit","16-bit-cpu","cpu","electronics","hardware","verilog"],"created_at":"2024-11-22T16:30:03.484Z","updated_at":"2025-10-28T16:45:53.661Z","avatar_url":"https://github.com/jes.png","language":"Slash","readme":"# SCAMP CPU\n\nSCAMP is my homebrew 16-bit CPU. It stands for something like \"Simple Computing and Arithmetic Microcoded Processor\".\n\nThe CPU is very primitive. It doesn't support interrupts, and has no MMU, and no concept of privilege levels. It currently runs\nat 1 MHz, above that the CompactFlash interface falls over. It runs a homebrew operating system, with a homebrew\nprogramming language and compiler, and can self-host the kernel and all of the system utilities.\nThe environment tastes a bit like an early Unix, but works like CP/M. I used the computer to complete\nalmost all of [Advent of Code 2021](https://adventofcode.com/2021/).\n\nMy Advent of Code solutions are here: https://github.com/jes/aoc2021\n\nI have some blog posts here: https://incoherency.co.uk/blog/tags/cpu.html and a web-based emulator available here: https://incoherency.co.uk/scamp/\n\nHere are some pictures:\n\n\u003cimg src=\"doc/computer.jpeg\" height=\"400\"\u003e \u003cimg src=\"doc/card-cage.jpeg\" height=\"400\"\u003e\n\nAnd here's a video with some explanation and an example session on real hardware:\n\n\u003ca href=\"https://www.youtube.com/watch?v=4sBB0iD6XvI\"\u003e\u003cimg width=\"400\" src=\"doc/youtube.png\"\u003e\u003c/a\u003e\n\n## Architecture\n\nIt is a 16-bit CPU. The bus is 16-bit, registers are 16-bit, addresses are 16-bit, and memory contents are\n16-bit. The upper 8 bits of an instruction select the opcode, and the lower 8 bits are available\nfor small immediate values. There is no support for: cache, interrupts, virtual memory, DMA, privilege rings,\nfloating point, and ~anything else that is not strictly necessary.\n\nHere is a diagram of the architecture:\n\n![](doc/architecture.png)\n\nFor more information, see [doc/UCODE.md](doc/UCODE.md) and [doc/ISA.md](doc/ISA.md).\n\n## Try it out\n\nThe easiest way to try it out is to use the web-based emulator at https://incoherency.co.uk/scamp/\n\nIf you want to run it locally, first you'll need to build everything. Try `make -j` in the root directory of this\nrepository. It probably won't work on the first attempt because it works with multiple different Makefiles that have\nannoying dependencies. Just run `make -j` twice or three times. If that doesn't do the trick, run `make` in `sys/` first, and then run\nit in `.`. Once you get to the point that it is only complaining about `emcc`, you're done, unless you also\nwant to build the web-based emulator.\n\nHaving built everything, you can go into `kernel/` and start it in the emulator with `./run`:\n\n    ~/scamp-cpu/kernel $ ./run\n    make: 'os.disk' is up to date.\n    SCAMP boot...\n    .......................................................OK\n    starting kernel...\n    loading init...\n          ____   ____    _    __  __ ____   __\n         / ___| / ___|  / \\  |  \\/  |  _ \\ / /__  ___\n         \\___ \\| |     / _ \\ | |\\/| | |_) / / _ \\/ __|\n          ___) | |___ / ___ \\| |  | |  __/ / (_) \\__ \\\n         |____/ \\____/_/   \\_\\_|  |_|_| /_/ \\___/|___/\n\n    $\n\nIf you know how to use Unix you'll probably understand how to use it. If you know how to use CP/M you'll probably\nunderstand how it works.\n\nIf you want, you can write SLANG programs using `kilo` and compile them with `slc`. You've probably never written\nSLANG before. You can learn how to use it by reading programs under `/src` (or `sys/` in the repo). It's mostly\nlike C but with fewer features and less safety.\n\n## How it's made\n\nI did these tasks, but working on several steps at a time (i.e. I didn't wait until after I had built the entire\ncomputer before thinking about microcode or the operating system):\n\n1. Create the CPU in Verilog, with a testbench for each part.\n2. Replace the raw Verilog with Verilog that only uses 74xx-compatible primitives\n   (e.g. https://github.com/TimRudy/ice-chips-verilog), but still passes the testbenches.\n3. Convert the 74xx-Verilog into KiCad schematics (by hand).\n4. Order the PCBs and components, solder up the PCBs, build a card cage, build a wooden case.\n5. Settle on the instruction set and write the microcode (see [doc/table.html](doc/table.html), available online at https://incoherency.co.uk/interest/table.html).\n5. Write a bootloader, kernel, shell, text editor, compiler, and various system utilities.\n\n## Next steps\n\nI suspect the computer will never be \"finished\", but some things I still want to work on are:\n\n#### Hardware\n\n - [ ] build a hardware multiplication card (and maybe division?)\n - [ ] build a hardware RNG\n\n#### Low-level software\n\n - [ ] make library blob self-hosting (compile within SCAMP/os)\n - [ ] write an strace-like debugging tool\n - [ ] write a DDT-like debugging tool\n - [ ] better facility for memory profiling (mainly to stop kilo and asm from running out of memory on large inputs)\n - [ ] atexit()\n - [ ] static initialisation of globals from constants (e.g. `var x = 5` at global scope should not take any code to initialise)\n - [ ] \"const\" variables (e.g. `const x = 5` should lead to `x` being replaced with the constant value `5` where possible)\n\n#### Other software\n\n - [ ] write a big-fixed-point arithmetic library\n - [ ] fixed-point mathematics: pow,tan,asin,acos,atan,atan2\n - [ ] write a FORTH implementation (should it run on bare metal or under SCAMP/os?)\n - [ ] write a Z-machine interpreter and port some text adventures\n - [ ] write some games (pong? breakout? tetris?)\n\nIf you happen to want to work on any of the above, I'd be happy to help you!\n\n## Resources\n\nI thoroughly recommend the Nand2Tetris course. https://nand2tetris.org/\n\nIf you want to do the exercises from Nand2Tetris without learning what a hardware-description language\nis, and without going through all the lectures, you can play https://nandgame.com/\n\nBen Eater's [videos on 8-bit CPU design](https://www.youtube.com/watch?v=HyznrdDSSGM\u0026list=PLowKtXNTBypGqImE405J2565dvjafglHU) are excellent and heavily influenced\nthe design of my CPU.\n\nI found the [YouTube playlist](https://www.youtube.com/playlist?list=PLOech0kWpH8-njQpmSNGSiQBPUvl8v3IM) for Nicolas Laurent's [compiler class](https://norswap.com/compilers/) quite helpful\nin writing the parser for the compiler.\n\nThe [Build Your Own Text Editor](https://viewsourcecode.org/snaptoken/kilo/) is a fantastic tutorial that walks you through implementing\n[antirez](https://github.com/antirez)'s [kilo](https://github.com/antirez/kilo) editor.\n\n[Balazs Markus](https://github.com/bazsimarkus)'s [8250 UART example](https://github.com/bazsimarkus/Simple-8250-UART-System-with-Arduino) is helpful.\n\nDaniel Tufvesson has a post that is a good starting point for understanding the [8-bit CompactFlash interface](http://www.waveguide.se/?article=8-bit-compact-flash-interface).\n\n[PickledDog](https://github.com/PickledDog) has a description of an [improvement to the RC2014 CompactFlash card](https://github.com/PickledDog/rc-cfcard) that might be helpful. Also [Bill Shen's comment on the RC2014 mailing list](https://groups.google.com/g/rc2014-z80/c/LmvGa6PZNhQ/m/H8jrbp86AQAJ).\n\nMichał Cierniak has a good blog post about [CompactFlash + 8255 interface card](https://ciernioo.wordpress.com/2015/02/10/compact-flash-8255-interface-card/) with lots\nof detail on how his CompactFlash interface works.\n\n[James Sharman](https://www.youtube.com/c/weirdboyjim) is building an interesting 8-bit pipelined CPU, and has good videos with lots of explanation on how it works.\n\nSCAMP is featured on the [Homebrew CPU ring](https://www.homebrewcpuring.org/) which also features many other interesting homebrew CPU designs.\n\n## Contact\n\nYou can email me on [james@incoherency.co.uk](mailto:james@incoherency.co.uk)\nor read my blog: [https://incoherency.co.uk/].\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjes%2Fscamp-cpu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjes%2Fscamp-cpu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjes%2Fscamp-cpu/lists"}