{"id":25296710,"url":"https://github.com/zeal8bit/zeal-bootloader","last_synced_at":"2025-10-28T03:30:23.155Z","repository":{"id":151984414,"uuid":"542548021","full_name":"Zeal8bit/Zeal-Bootloader","owner":"Zeal8bit","description":"Bootloader for Zeal 8-bit Computer","archived":false,"fork":false,"pushed_at":"2024-05-25T15:29:59.000Z","size":296,"stargazers_count":21,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-06-02T17:36:24.192Z","etag":null,"topics":["bootloader","z80","zeal","zeal8bit"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zeal8bit.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":"2022-09-28T11:09:10.000Z","updated_at":"2024-05-25T15:29:55.000Z","dependencies_parsed_at":"2024-04-28T11:26:48.264Z","dependency_job_id":null,"html_url":"https://github.com/Zeal8bit/Zeal-Bootloader","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeal8bit%2FZeal-Bootloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeal8bit%2FZeal-Bootloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeal8bit%2FZeal-Bootloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeal8bit%2FZeal-Bootloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zeal8bit","download_url":"https://codeload.github.com/Zeal8bit/Zeal-Bootloader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238585159,"owners_count":19496442,"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":["bootloader","z80","zeal","zeal8bit"],"created_at":"2025-02-13T02:59:05.204Z","updated_at":"2025-10-28T03:30:22.507Z","avatar_url":"https://github.com/Zeal8bit.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"img/title.png\" alt=\"Zeal Bootloader title\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"Licence\" /\u003e\n    \u003c/a\u003e\n    \u003cp align=\"center\"\u003eA bootloader entirely written in Z80 assembly, for Zeal 8-bit Computer, a homebrew 8-bit computer based on a real Z80 CPU\u003c/p\u003e\n\u003c/p\u003e\n\n## About this project\n\nThe goal of this project is to provide a compact bootloader for Zeal 8-bit Computer that lets us perform several operations directly from the computer itself, such as booting different operating systems, flashing the ROM, testing the hardware, etc..., without the need of any external devices.\n\n## Screenshots\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"img/menu_uart.png\" alt=\"Zeal Bootloader menu\" /\u003e\n    \u003cdiv align=\"center\"\u003eZeal 8-bit Bootloader using the UART\u003c/div\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"img/menu_video.png\" alt=\"Zeal Bootloader menu\" /\u003e\n    \u003cdiv align=\"center\"\u003eZeal 8-bit Bootloader using Zeal 8-bit Video Card\u003c/div\u003e\n\u003c/p\u003e\n\n## Features\n\nAs you can see from the menu itself, several feature have been implemented:\n\n* Communication over UART or over the video board¹\n* Auto-boot on startup after after a few seconds¹\n* Up to 9 operating systems or programs can be set up to boot from the menu. In the example above, only one entry is present: Zeal 8-bit OS. The numbers between the parenthesis represent the physical address (in ROM) and the virtual address respectively. In the output above, Zeal 8-bit OS is flashed at address **0x4000** in the ROM, it will be mapped at virtual address **0x0000** when booted.\n* Program can be sent through UART, and booted **directly**. No need to flash the ROM, handy for development and testing programs.\n* New entries can be added as bootable systems, directly from the bootloader itself.\n* Entries can be deleted directly from the bootloader. Note that it is not possible to delete all entries, there must at least be one remaining entry at all time.\n* Buffered changes. To prevent mistakes when adding and deleting entries, the changes are first saved to RAM. The changes can then be flushed (**s** option) or discard (reboot the system).\n* Baudrate can be changed for the current bootloader session (not saved after a reboot).\n* Test Zeal 8-bit Computer hardware: including RAM size, Flash/ROM size, I2C EEPROM, I2C RTC, and PS/2 keyboard.\n\n¹: These options are configurable via the `config.asm` file.\n\n## Building the project\n\n### Requirements\n\nAt the moment, the project has only been assembled on Linux (Ubuntu 20.04 and 22.04), it should be compatible with Mac OS and Windows as long as you have:\n\n* bash\n* git (to clone this repo)\n* make\n* z88dk v2.2 (or later). Only its assembler, `z80asm`, is strictly required. The latest version of `z80asm` must be used as earlier versions don't have support for `MACRO`.\n\nTo install z88dk, please [check out their Github project](https://github.com/z88dk/z88dk).\n\n### Configuration\n\nBefore building the bootloader, open and modify, if necessary, the configuration file `include/config.asm`.\n\nIn this file, any macro that is not set (commented) or set to 0 will be considered disabled.\n\n### Building\n\nAfter the configuration is saved, you can build the bootloader thanks to the command:\n```\nmake\n```\n\nAfter compiling, the folder `build/` should contain the binary `bootloader.bin` and `bootloader.map`. The first one is the program itself, whereas the second is a text file containing all the (debug) symbols of the binary.\n\nThat map file is only useful when debugging the bootloader, mainly with [Zeal 8-bit Computer emulator](https://github.com/Zeal8bit/Zeal-WebEmulator).\n\n## Transferring data over UART\n\nAs you saw in the features list, it is possible to send programs through UART, either to load and execute it or to flash it to the ROM. On the host computer, depending on whether you are using Linux, Mac OS or Windows, the procedure is different.\n\nLet's say we want to flash a newer version of Zeal 8-bit OS, `os.bin` file, at physical address **0x4000** in ROM and with a size of **0x51d8** bytes (20952 bytes in decimal).\n\nIn the bootloader, after pressing the key for \"Flash/Program the ROM\" (**f** key), we see:\n\n```\nNumbers must be provided in hexadecimal\nROM address to flash, aligned on 4KB:\n```\n\nWe specify **4000**, no need to type the **0x** prefix here, and press enter:\n\n```\nNumbers must be provided in hexadecimal\nROM address to flash, aligned on 4KB: 4000\nBinary size:\n```\n\nThe binary size is prompted, we type **51d8**, same, no need for the prefix:\n\n```\nNumbers must be provided in hexadecimal\nROM address to flash, aligned on 4KB: 4000\nBinary size: 51d8\nPlease send file...\n```\n\nHere, we have to send the file as a \u003cu\u003e**raw binary**\u003c/u\u003e. Let's see how to do this on Linux and Windows.\n\n### Linux\n\n**Note:** Here, I assume that the node used to communicate with Zeal 8-bit Computer through UART is `/dev/ttyUSB0`. If yours is different, replace it in the commands below (should be `/dev/ttyUSBx` or `/dev/ttyACMx` depending on your USB-to-TTL adapter).\n\nOn Linux, open a new terminal, configure the TTY as raw:\n\n```\nstty -F /dev/ttyUSB0 raw\n```\n\nAnd set the correct baudrate, which is 57600 by default:\n\n```\nstty -F /dev/ttyUSB0 57600\n```\n\nAfter this, it is possible to send the file thanks to **cat**:\n\n```\ncat os.bin \u003e /dev/ttyUSB0\n```\n\nOn the host, wait until the prompt is back. Once the transfer is finished, the bootloader (monitor) will show the message:\n\n```\nFlashing in progress, do not turn off...\n```\n\nWait until it finishes and that's it!\n\n### Windows\n\nOn Windows, only Tera Term can send raw binaries (or at least, it's the only one I have found that can do it). To do so, click on \"File\" and \"Send file\":\n\n\u003cimg src=\"img/terat_flash_1.png\" class=\"mobile-center\" alt=\"Tera Term Flash 1\" width=\"70%\" /\u003e\n\nLocate your file **and make sure to tick binary box!**\n\n\u003cimg src=\"img/terat_flash_2.png\" class=\"mobile-center\" alt=\"Tera Term Flash 2\" width=\"70%\" /\u003e\n\nClick on \"Open\", a popup should now show up, wait until the file finishes transferring.\n\nOnce the transfer is finished, the popup window should close itself, and the bootloader will show the message:\n\n```\nFlashing in progress, do not turn off...\n```\n\nWait until it finishes and that's it!\n\n\n## Why this project?\n\nThis project was born when it was decided to use start selling few samples of Zeal 8-bit Computer to developers. As the main operating system of the computer, [Zeal 8-bit OS](https://github.com/Zeal8bit/Zeal-8-bit-OS), is still under development. Thus, I wanted to provide a way for developers and users to boot several systems or software without the need to re-flash the ROM every time.\n\nThe logical feature to implement with such multi-boot capability is flash directly from the board, without the need of an external flasher, and so, without taking out the ROM chip.\n\nOne requirement I really wanted to see and implement is the possibility to flash a newer version of the bootloader, directly from the bootloader.\n\n\n## Contact\n\nFor any suggestion or request, you can contact me at contact [at] zeal8bit [dot] com\n\nOr, you can join Zeal 8-bit projects [Discord server](https://discord.gg/UzEjwRvBBb).\n\nFor features requests, you can also open an issue or a pull request.\n\n## Contributing\n\nContributions are welcome! Feel free to fix any bug that you may see or encounter, or implement any feature that you find important.\n\nTo contribute:\n  * Fork the Project\n  * Create your feature Branch (*optional*)\n  * Commit your changes. Please make a clear and concise commit message (*)\n  * Push to the branch\n  * Open a Pull Request\n\n\n(*) A good commit message is as follow:\n```\nModule: add/fix/remove a from b\n\nExplanation on what/how/why\n```\nFor example:\n```\nFlash: add the possibility to flash programs bigger than 48KB\n```\n\n## License\n\nDistributed under the Apache 2.0 License. See `LICENSE` file for more information.\n\nYou are free to use it for personal and commercial use, the boilerplate present in each file must not be removed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeal8bit%2Fzeal-bootloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeal8bit%2Fzeal-bootloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeal8bit%2Fzeal-bootloader/lists"}