{"id":20658611,"url":"https://github.com/gergoerdi/clash-compucolor2","last_synced_at":"2025-04-19T13:21:20.760Z","repository":{"id":53004086,"uuid":"199111529","full_name":"gergoerdi/clash-compucolor2","owner":"gergoerdi","description":"Clash implementation of the Compucolor II home computer","archived":false,"fork":false,"pushed_at":"2021-11-06T04:15:57.000Z","size":253,"stargazers_count":25,"open_issues_count":1,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2023-04-22T16:46:48.622Z","etag":null,"topics":["clash","compucolor2","emulator","fpga","haskell","intel-8080","retrocomputing"],"latest_commit_sha":null,"homepage":"","language":"Haskell","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/gergoerdi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-27T03:41:43.000Z","updated_at":"2022-10-19T17:39:20.000Z","dependencies_parsed_at":"2022-09-07T22:52:23.838Z","dependency_job_id":null,"html_url":"https://github.com/gergoerdi/clash-compucolor2","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gergoerdi%2Fclash-compucolor2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gergoerdi%2Fclash-compucolor2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gergoerdi%2Fclash-compucolor2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gergoerdi%2Fclash-compucolor2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gergoerdi","download_url":"https://codeload.github.com/gergoerdi/clash-compucolor2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224955690,"owners_count":17398096,"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","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":["clash","compucolor2","emulator","fpga","haskell","intel-8080","retrocomputing"],"created_at":"2024-11-16T18:27:08.600Z","updated_at":"2024-11-16T18:27:09.190Z","avatar_url":"https://github.com/gergoerdi.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Compucolor II Home Computer\n\nThis is a Clash implementation of the 1977 Compucolor II home computer\nmanufactured by the CompuColor Corporation until 1980.\n\nThis code is part of the book *Retrocomputing with Clash: Haskell for\nFPGA Hardware Design* at \u003chttps://unsafePerform.IO/retroclash/\u003e.\n\n![Compucolor II just booting up in simulation](vga-full-boot.png)\n\n## Hardware architecture\n\n* **CPU**: Intel 8080.\n\n* **Video**: SMC CRT 5027 video chip generates a 64⨯32 cell\n  screen. Each cell is either a character index into a built-in font\n  ROM, or a 2⨯4 bitmap with double-width pixels. Characters can\n  optionally be rendered at double height.\n\n  The CPU has two ways of accessing the backing 2K video RAM: slow\n  access (preempted by the video system) and fast access (leading to\n  video glitches in the meantime).\n\n* **IO**: TMS 5501 IO controller handles interrupt servicing, keyboard\n  input, serial IO and disk IO.\n\n\n## Clash implementation\n\n* **CPU**: Implemented based on abstract descriptions of Intel 8080 ISA,\n  with no reference to real implementation. Instructions take the same\n  number of cycles as a real Intel 8080, which is needed for the tight\n  timing constraints of the floppy drive.\n\n* **Video**: Standard 800⨯600@60Hz VGA, with 40MHz pixel clock.\n  Logical \"pixels\" are scaled 2⨯2. Hardware cursor and vertical\n  scrolling is implemented via the CRT 5027.\n\n* **Framebuffer**: Since the video system needs access to both\n  even-addressed (character index) and odd-addressed (color etc.)\n  bytes, preferably in the same cycle, the framebuffer is split into\n  two 2K RAMs, one holding the even and the other holding the odd\n  addresses. The CPU reads/writes these through special logic handling\n  the least significant bit of the original (single-byte) address.\n\n* **IO**: The TMS 5501 IO controller is implemented fully: timers,\n  parallel IO, interrupt servicing and UART are all implemented based\n  on the original data sheet. Instead of the fixed clock divisor of\n  128 in the real TMS 5501 (designed for a 2 MHz clock), this\n  implementation divides into 64 μs regardless of the clock speed.\n\n* **Input**: PS/2 keyboard events are decoded into a virtual key\n  matrix, which is connected to the TMS 5501.\n  \n* **Disk drive**: Virtual \"disk\" served from a small block ROM,\n  connected to the serial port of the TMS 5501.\n\n* **Turbo switch**: If unset, the CPU is slowed down by idling for 19\n  out of every 20 cycles. This way, even though it runs at the pixel\n  clock speed of 40 MHz, real-time games are still playable. \n\n# Simulation\n\nSimulations of several abstraction levels are included. Most come in\ntwo flavors: using Clash, or using Verilator. The Verilator ones\ngenerally perform much better, but require installing Verilator and\ncompiling with the `verilator` Cabal flag.\n\n## Limitations\n\n* The CRT 5027 video controller only implements the 64⨯32 character\n  mode used by the Compucolor II\n  \n* The serial data rate of the TMS 5501 is fixed at 9600 bps\n\n* Keyboard input is not implemented in any of the simulations\n\n# Synthesizing\n\nIncluded are Shake rules to build for various hobbyist FPGA dev\nboards:\n\n* The Xilinx Artix-7 based Nexys A7 50T. This uses the Xilinx Vivado\n  toolchain.\n\n* TODO: The Xilinx Spartan-6 based Papilio Pro or the Spartan-3 based\n  Papilio One, both with the Arcade mega-wing. These use the Xilinx ISE\n  toolchain.\n\nMake a file called `build.mk` with content similar to the following:\n\n```\nTARGET = nexys-a7-50t\nISE = ~/prog/docker/xilinx-ubuntu-12.04/run\nVIVADO = ~/prog/docker/xilinx-2019.1-ubuntu-18.04/run\nDISK = image/disks/hangman.ccvf\n```\n\nThe `ISE` and `VIVADO` fields are to optionally wrap invocations of\nthe Xilinx ISE / Vivado toolchain in case you want to run them via\nStack, Docker, Nix, etc.\n\nThen you can build into an FPGA configuration bitfile by running the\nincluded `mk` script.\n\n\n# Useful links\n\n* [Wikipedia](https://en.wikipedia.org/wiki/Compucolor_II)\n* [Oldcomputers.net](http://oldcomputers.net/compucolor-ii.html)\n* [Compucolor.org](http://www.compucolor.org/): all things Compucolor\n  II, including heaps of original documentation and a software\n  emulator written in JavaScript.\n* [CRT5027 page at the IntelliWiki](http://wiki.intellivision.us/index.php?title=TMS9927_CRT_Controller)\n* [TMS5501 datasheet](https://amaus.net/static/S100/TI/datasheet/Texas%20Instruments%20TMS5501%20Specification%20197608.pdf)\n* [Intel 8080 opcodes](http://pastraiser.com/cpu/i8080/i8080_opcodes.html)\n* [Intel 8080 opcodes](http://www.classiccmp.org/dunfield/r/8080.txt)\n* [Monadic descriptions of CPUs in Clash](https://gergo.erdi.hu/blog/2018-09-30-composable_cpu_descriptions_in_c_ash,_and_wrap-up_of_retrochallenge_2018_09/)\n* [Integrating Verilator and Clash](https://gergo.erdi.hu/blog/2020-05-07-integrating_verilator_and_clash_via_cabal/)\n* [Nexys A7 FPGA dev board](https://reference.digilentinc.com/reference/programmable-logic/nexys-a7/start)\n* [Papilio Pro FPGA dev board](https://papilio.cc/index.php?n=Papilio.PapilioPro)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgergoerdi%2Fclash-compucolor2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgergoerdi%2Fclash-compucolor2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgergoerdi%2Fclash-compucolor2/lists"}