{"id":24791466,"url":"https://github.com/jetsetilly/relocatebb","last_synced_at":"2025-03-24T14:23:01.045Z","repository":{"id":246111813,"uuid":"769713928","full_name":"JetSetIlly/relocateBB","owner":"JetSetIlly","description":"Converts Batari Basic DPC+ ROMs for use on PlusCart and UnoCart","archived":false,"fork":false,"pushed_at":"2024-06-25T20:40:48.000Z","size":1189,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-29T19:17:00.513Z","etag":null,"topics":["atari2600"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JetSetIlly.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-09T21:04:30.000Z","updated_at":"2024-10-06T15:15:39.000Z","dependencies_parsed_at":"2024-06-25T22:56:07.318Z","dependency_job_id":"8fa0acd6-6291-4fd1-bea0-018e11ddd599","html_url":"https://github.com/JetSetIlly/relocateBB","commit_stats":null,"previous_names":["jetsetilly/relocatebb"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JetSetIlly%2FrelocateBB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JetSetIlly%2FrelocateBB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JetSetIlly%2FrelocateBB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JetSetIlly%2FrelocateBB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JetSetIlly","download_url":"https://codeload.github.com/JetSetIlly/relocateBB/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245285627,"owners_count":20590447,"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":["atari2600"],"created_at":"2025-01-29T19:17:03.609Z","updated_at":"2025-03-24T14:23:01.025Z","avatar_url":"https://github.com/JetSetIlly.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RelocateBB\n\nRelocateBB is a tool to be used with [Batari Basic](https://github.com/batari-Basic/batari-Basic) ROM files. It allows games that use the DPC+ kernel to be run on the PlusCart or the UnoCart. It will do nothing for bB games that that don't use the DPC+ kernel - those games will already run on the PlusCart and UnoCart.\n\n## Usage\n\nRun RelocateBB from the command line. The `-help` argument shows the usage and the available options\n\n```\nUsage: relocateBB_linux_amd64 (options) [list of rom files]\n  -ace\n    \tadd ACE header to converted binary (default true)\n  -check\n    \tchecks for valid PlusROM DPC+ and displays version information\n```\n\nThe `-ace` option should almost always be left at the default value of true.\n\nThe `-check` option provides information about a file, indicating whether its a DPC+ file or a converted DPC+ file. In the case of a converted file the output will include version number information about hashes of the driver and custom code sections.\n\n#### Unconverted DPC+ file\n\n```\nrelocateBB -check Unholy_demo_2020_07_06.bin \noriginal DPC+ file\ndriver md5: 5f80b5a5adbe483addc3f6e6f1b472f8\n```\n\n#### Converted DPC+ file\n\n```\nrelocateBB -check Unholy_demo_2020_07_06.ace \ndriver md5: ef12c0d0d6b985c5147b9deba63d68b6\ndriver version: v1.07a\nbb md5: 5d3f5788a71fb24a678cb6622702c3dd\n```\n\n\n## Developer Detail\n\n### ACE driver\n\n#### Compilation\n\nThe ACE driver is built with the GNU Arm Embedded Toolchain version of GCC. Full version banner of the compiler below.\n\n```\narm-none-eabi-gcc (Arm GNU Toolchain 12.2.Rel1 (Build arm-12.24)) 12.2.1 20221205\nCopyright (C) 2022 Free Software Foundation, Inc.\nThis is free software; see the source for copying conditions.  There is NO\nwarranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n```\n\nReference the `build.sh` file in the `ace/` directory for which compile time options were used.\n\nThe build process requires access to the [United Carts of Atari](https://github.com/Al-Nafuur/United-Carts-of-Atari) SDK. Download or `git clone` the repository into the `ace/` directory.\n\n#### ACE Driver Versions\n\nThe ACE driver is versioned and any substantial change to the driver code *must* be accompanied by a change in the version number. The version number is in the driver asm file located at `ace/src/ace.asm`\n\nThe relevant section of the ace.asm file is. Please follow the directives in the commentary.\n\n```\n; driver name should always begin with the string \"DPCp \" (including the space)\n;\n; it should also include a version string of the form \"vX.YY\" where X and YY are\n; integers. for the 'alt' driver the suffix 'a' should be included\n;\n; nothing else should be included in the driver name apart from whitespace\n;\n; finally, the driver name should be exactly string 16 chars wide exactly \n;\t\t     \"                \"\n\tIF ALT == 1\n\t\tdc.b \"DPCp v1.07a     \"\n\tELSE\n\t\tdc.b \"DPCp v1.07      \"\n\tENDIf\n```\n\n**NOTE**: The version string is `DPCp` and not `DPC+` in order to distinguish it from DPC+ binaries compiled for the Harmony type cartridges. Failure to distinguish the two types of binary would likely result in confusion. \n\n#### The 'ALT' driver\n\nThe 'ALT' driver is a small variation of the standard DPCp driver which is required when converting some DPC+ ROMs. Whether the 'ALT' type is required depends on the version of the Harmony driver being replaced.\n\n| MD5 of Harmony Driver            | Replace |\n|----------------------------------|---------|\n| 17884ec14f9b1d06fe8d617a1fbdcf47 | NORMAL  |\n| 5f80b5a5adbe483addc3f6e6f1b472f8 | ALT     |\n| 8dd73b44fd11c488326ce507cbeb19d1 | ALT     |\n| b328dbdf787400c0f0e2b88b425872a5 | NORMAL  |\n\nTechnical detail: The 'ALT' driver differs from the 'NORMAL' driver in that the counter bits of the fraction fetcher are reset when the 'low' byte of the fetcher is set. It's such a small difference and yet using the wrong driver can sometimes be noticed in the form of playfield shimmer. \n\nAs indicated in the `ACE Driver Versions` section above, the 'ALT' driver is distinguished with an 'a' appended to the version number.\n\n### bB Custom Code\n\n#### Compilation\n\nThe bB custom code is built with the same version of the GNU Arm Embedded Toolchain. Use the `make` command\nto build.\n\n#### Changes from the Original\n\nThe driver code is mostly the same as found in the Batari Basic [include/custom](https://github.com/batari-Basic/batari-Basic/tree/d0b12c1b257156645df5371da48bcbbab7682580/includes/custom) directory. However, there are some significant changes.\n\nThe most significant change is to the address space the program operates with. The first group of addresses are found in the `custom.S` and `custom.boot.S` files. The table below summarises how address ranges are changed.\n\n| Old Origin   | Old Memtop   | New Origin   | New Memtop   |\n|--------------|--------------|--------------|--------------|\n| `0x00000000` | `0x0fffffff` | `0x20000000` | `0x2000ffff` |\n| `0x40000000` | `0x4fffffff` | `0x20010000` | `0x20017fff` |\n\nAddresses are also found in the `main.c` file. These are changed in the same way.\n\nThere are also changes to the ordering of code in the `main.c` file. The logic is the same but some rearrangement of code was required in order to produce a small enough binary (2196 bytes or fewer). A good diff tool will show all the changes.\n\nFinally, there are changes to the `Makefile`. The target architecture has been changed to `armv6-m` and the optimisation has been set to `-Oz`. This is a relatively new flag to GCC and requests more aggressive size optimisation that `-Os`. Indeed, the principle reason for the GCC v12.0 requirement is access to the `-Oz` flag.\n\nThe GCC debugging flags have also been ammended. The singular `-g` flag has been replaced with `-g3 -gdwarf-4` `-gstrict-dwarf`. The debugging information isn't included in the final custom binary but it is included in the interim elf file. Also for debugging purposes the Makefile now also produces a `objdump` file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetsetilly%2Frelocatebb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjetsetilly%2Frelocatebb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetsetilly%2Frelocatebb/lists"}