{"id":16547536,"url":"https://github.com/hainesr/mos6502","last_synced_at":"2026-05-26T20:31:31.382Z","repository":{"id":56884547,"uuid":"302159758","full_name":"hainesr/mos6502","owner":"hainesr","description":"A ruby implementation of the 6502 microprocessor","archived":false,"fork":false,"pushed_at":"2021-05-19T18:45:23.000Z","size":321,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-07T23:44:23.600Z","etag":null,"topics":["6502","6502-processor","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hainesr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-07T21:03:39.000Z","updated_at":"2022-04-30T14:11:35.000Z","dependencies_parsed_at":"2022-08-20T23:40:49.359Z","dependency_job_id":null,"html_url":"https://github.com/hainesr/mos6502","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hainesr/mos6502","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hainesr%2Fmos6502","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hainesr%2Fmos6502/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hainesr%2Fmos6502/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hainesr%2Fmos6502/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hainesr","download_url":"https://codeload.github.com/hainesr/mos6502/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hainesr%2Fmos6502/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33538659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["6502","6502-processor","ruby"],"created_at":"2024-10-11T19:14:38.935Z","updated_at":"2026-05-26T20:31:31.367Z","avatar_url":"https://github.com/hainesr.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ruby MOS 6502\n\nA ruby implementation of the [MOS Technology 6502 microprocessor][wp-6502].\n\n![Image of a MOS Technology 6502 microprocessor (from Wikipedia)](https://upload.wikimedia.org/wikipedia/commons/4/49/MOS_6502AD_4585_top.jpg)\n\n[![Gem Version](https://badge.fury.io/rb/mos6502.svg)](https://badge.fury.io/rb/mos6502)\n![CI](https://github.com/hainesr/mos6502/workflows/CI/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/github/hainesr/mos6502/badge.svg?branch=main)](https://coveralls.io/github/hainesr/mos6502?branch=main)\n[![Maintainability](https://api.codeclimate.com/v1/badges/d3c28f3d1c4cee8099fb/maintainability)](https://codeclimate.com/github/hainesr/mos6502/maintainability)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'mos6502'\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install mos6502\n\n## Usage\n\nThe entry point to this library is `Mos6502::Cpu`. You can create a new `Cpu` with the program counter (PC) set to a specific memory address as follows:\n\n```ruby\ncpu = Mos6502::Cpu.new(initial_pc: 0x400)\n```\n\nYou can load a snippet of code like this:\n\n```ruby\ncpu.load!([0xa9, 0x33, 0x69, 0x55])\n```\n\n`Cpu#load!` also resets the CPU; all memory is cleared first, then the registers are set to zero, the PC is returned to its initial value, the stack pointer (SP) is reset to `0xff` and the status bits are set to their defaults.\n\nThere is no assembler (yet?). The above code is:\n\n```\nLDA #$33 ; load immediate\nADC #$55 ; add with carry\n```\n\nIt will load the hex value `0x33` (51) into the accumulator and add the hex value `0x55` (85) to it and store the result back in the accumulator.\n\nTo run the next instruction, call `Cpu#step`. The PC will be advanced to point to the next instruction. To run the above code, which is just two instructions, use:\n\n```ruby\ncpu.step\ncpu.step\n```\n\nYou can then inspect the current state of the CPU with:\n\n```ruby\nputs cpu.inspect\n\n# a: 0x88, x: 0x00, y: 0x00, sp: 0xff, pc: 0x0404, op: 0x00, status: 0b11110000\n```\n\nYou can see here that the accumulator (`a`) holds the result of `0x33` + `0x55` = `0x88` and that the PC has moved on 4 places to `0x404`. You can also see from the status bits that the result is negative in two's complement (bit 7) and that overflow has occurred (bit 6).\n\nFor more complex code, you will need to load in an assembled image:\n\n```ruby\nimage = File.read(IMAGE_PATH)\ncpu.load_image!(image, 0x400)\n```\n\nYou will need to know the entry point, and set the initial PC when initializing the `Cpu` upfront. The above example loads the image at memory location 1024. `Cpu#load_image!` will reset the CPU in the same way as `Cpu#load!` above. If you need to load an image in parts (e.g. assembled code and data) you can use `Cpu#load_image`, which is non-destructive.\n\nThere is loads more information on the 6502, and how to program it here:\n\n* [Obelisk][obelisk]\n* [6502.org][6502org]\n* [Visual 6502][vis6502]\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\n### 6502 test suites\n\nThis repository includes external test suites to more comprehensively test all the features of the 6502 microprocessor. They are not run by default because they can take a few minutes to complete, but can be turned on with environment variables passed into `rake`. Once this code supports all of a test suite's features it will be run by default in CI.\n\n#### Klaus Dormann's test suite\n\nThis is included as a submodule. Once you've initialized it you can run it as part of the normal test suite with:\n\n```shell\nMOS6502_KLAUS2M5=on rake\n```\n\nIf you want to see a full debug stream of it running, use `MOS6502_KLAUS2M5=debug` instead.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/hainesr/mos6502.\n\n\n## Code of Conduct\n\nThis project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct][coc].\n\nEveryone interacting in the MOS 6502 project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.\n\n## Licence\n\nCopyright (c) 2020, Robert Haines.\n\nReleased under the BSD Licence. See LICENCE for details.\n\n[wp-6502]: https://en.wikipedia.org/wiki/MOS_Technology_6502\n[coc]: https://github.com/hainesr/mos6502/blob/master/CODE_OF_CONDUCT.md\n[obelisk]: http://www.obelisk.me.uk/6502/\n[6502org]: http://www.6502.org/\n[vis6502]: http://www.visual6502.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhainesr%2Fmos6502","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhainesr%2Fmos6502","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhainesr%2Fmos6502/lists"}