{"id":15489760,"url":"https://github.com/theandrew168/derzforth","last_synced_at":"2025-04-22T18:27:39.266Z","repository":{"id":46228472,"uuid":"343254990","full_name":"theandrew168/derzforth","owner":"theandrew168","description":"Bare-metal Forth implementation for RISC-V","archived":false,"fork":false,"pushed_at":"2024-02-09T04:42:12.000Z","size":78,"stargazers_count":51,"open_issues_count":4,"forks_count":5,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-19T13:09:41.212Z","etag":null,"topics":["bare-metal","forth","longan-nano","risc-v","wio-lite"],"latest_commit_sha":null,"homepage":"","language":"Assembly","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/theandrew168.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":"2021-03-01T01:19:21.000Z","updated_at":"2025-04-11T06:01:12.000Z","dependencies_parsed_at":"2025-03-04T04:30:52.130Z","dependency_job_id":"c5ccd036-b65c-4bb3-8f34-167be453ef39","html_url":"https://github.com/theandrew168/derzforth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theandrew168%2Fderzforth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theandrew168%2Fderzforth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theandrew168%2Fderzforth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theandrew168%2Fderzforth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theandrew168","download_url":"https://codeload.github.com/theandrew168/derzforth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250296539,"owners_count":21407040,"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":["bare-metal","forth","longan-nano","risc-v","wio-lite"],"created_at":"2024-10-02T07:07:41.606Z","updated_at":"2025-04-22T18:27:39.243Z","avatar_url":"https://github.com/theandrew168.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DerzForth\nBare-metal Forth implementation for RISC-V RV32I core.\n\n## About\nForth was initially designed and created by [Charles Moore](https://en.wikipedia.org/wiki/Charles_H._Moore).\nMany folks have adapted its ideas and principles to solve their own problems.\n[Moving Forth](http://www.bradrodriguez.com/papers/moving1.htm) by Brad Rodriguez is an amazing source of Forth implementation details and tradeoffs.\nIf you are looking for some introductory content surrounding the Forth language in general, I recommend the book [Starting Forth](https://www.forth.com/starting-forth/) by Leo Brodie.\n\nThis implementation's general structure is based on [Sectorforth](https://github.com/cesarblum/sectorforth) by Cesar Blum.\nHe took inspiration from a [1996 Usenet thread](https://groups.google.com/g/comp.lang.forth/c/NS2icrCj1jQ/m/ohh9v4KphygJ) wherein folks discussed requirements for a minimal yet fully functional Forth implementation.\n\n## Requirements\nThe hardware requirements for running DerzForth are minimal and straightforward:\n* At least 16KB of RAM (define `RAM_BASE_ADDR` and `RAM_SIZE`)\n* At least 16KB of ROM (define `ROM_BASE_ADDR` and `ROM_SIZE`)\n* Serial UART (implement `serial_init`, `serial_getc`, and `serial_putc`)\n\nDerzForth has been tested on the following RISC-V development boards:\n* [Longan Nano](https://www.seeedstudio.com/Sipeed-Longan-Nano-RISC-V-GD32VF103CBT6-DEV-Board-p-4725.html)\n* [Longan Nano Lite](https://docs.platformio.org/en/latest/boards/gd32v/sipeed-longan-nano-lite.html)\n* [Wio Lite](https://www.seeedstudio.com/Wio-Lite-RISC-V-GD32VF103-p-4293.html)\n* [GD32 Dev Board](https://www.seeedstudio.com/SeeedStudio-GD32-RISC-V-kit-with-LCD-p-4303.html)\n* [HiFive1 Rev B](https://www.sifive.com/boards/hifive1-rev-b)\n\n## Setup\nIf you are unfamiliar with [virtual environments](https://docs.python.org/3/library/venv.html), I suggest taking a brief moment to learn about them and set one up.\nThe Python docs provide a great [tutorial](https://docs.python.org/3/tutorial/venv.html) for getting started with virtual environments and packages.\n\nDerzForth is an assembly program based on the [Bronzebeard](https://github.com/theandrew168/bronzebeard) project.\nConsult Bronzebeard's project page for how to get it all setup (it's pretty easy and works on all major platforms).\n\nBronzebeard (and a few other tools) can be installed via pip:\n```\npip install -r requirements.txt\n```\n\n### Boards\nSome boards require a USB to UART cable in order to program and/or interact.\nI recommend the [CP2012](https://www.amazon.com/HiLetgo-CP2102-Converter-Adapter-Downloader/dp/B00LODGRV8).\n\n#### Longan Nano [Lite]\nFor this board, the only setup necessary is a USB to UART cable.\n\n* Attach TX to pin R0 (PA10)\n* Attach RX to pin T0 (PA9)\n* Attach GND to pin GND\n* Attach 3.3V to pin 3V3 (be sure not to supply 5V to 3.3V or vice versa)\n\n#### Wio Lite\nFor this board, the only setup necessary is a USB to UART cable.\n\n* Attach TX to pin PA10\n* Attach RX to pin PA9\n* Attach GND to GND\n* Attach 3.3V to 3V3 (be sure not to supply 5V to 3.3V or vice versa)\n\n#### GD32 Dev Board\nFor this board, the only setup necessary is a USB to UART cable.\n\n* Attach TX to pin RXD (PA10)\n* Attach RX to pin TXD (PA9)\n* Attach GND to GND\n* Attach 3.3V to 3V3 (be sure not to supply 5V to 3.3V or vice versa)\n\n#### HiFive1 Rev B\nProgramming this board requires [Segger's J-Link software](https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack).\nThese tools work on all major platforms but depend on [Java](https://openjdk.java.net/install/).\n\nAs far as cables go, just a single USB to Micro-USB cable is necessary.\n\n* Plug the Micro-USB cable into the Micro-USB port\n\n## Build\nWith Bronzebeard installed:\n```\nbronzebeard -c -i boards/\u003ctarget_board\u003e/ --include-definitions derzforth.asm\n```\n\n## Program\nSome boards share a common method of programming and interacting.\n\n### GD32VF103 Boards\nEnable boot mode on your given device:\n* **Longan Nano** - press BOOT, press RESET, release RESET, release BOOT\n* **Wio Lite** - flip BOOT switch to 1, press and release RESET\n* **GD32 Dev Board** - swap BOOT0 jumper to 3V3, press and release RESET, swap BOOT0 jumper to GND\n\nTo get a list of available serial ports, run the following command:\n```\npython3 -m serial.tools.list_ports\n```\n\nThen, program the device over serial UART:\n```\nstm32loader -p \u003cdevice_port\u003e -ewv bb.out\n```\n\nHere are some examples:\n```\n# Windows\nstm32loader -p COM3 -ewv bb.out\n# macOS\nstm32loader -p /dev/cu.usbserial-0001 -ewv bb.out\n# Linux\nstm32loader -p /dev/ttyUSB0 -ewv bb.out\n```\n\n### FE310-G002 Boards\nAfter converting the output binary to [Intel HEX](https://en.wikipedia.org/wiki/Intel_HEX) format, Segger J-Link handles the rest:\n```\nbin2hex.py --offset 0x20010000 bb.out bb.hex\nJLinkExe -device FE310 -if JTAG -speed 4000 -jtagconf -1,-1 -autoconnect 1 scripts/hifive1_rev_b.jlink\n```\n\n## Execute\n\n### GD32VF103 Boards\nAfter programming, put the device back into normal mode:\n* **Longan Nano** - press and release RESET\n* **Wio Lite** - flip BOOT switch to 0, press and release RESET\n* **GD32 Dev Board** - TODO how does this board work?\n\n### FE310-G002 Boards\nThe J-Link command from the previous step will automatically reset the chip after programming!\n\n## Interact\nTo interact with the device, the same port as above can used with [pySerial's builtin terminal](https://pyserial.readthedocs.io/en/latest/tools.html#module-serial.tools.miniterm):\n```\npython3 -m serial.tools.miniterm \u003cdevice_port\u003e 115200\n```\n\nHere are some examples:\n```\n# Windows\npython3 -m serial.tools.miniterm COM3 115200\n# macOS\npython3 -m serial.tools.miniterm /dev/cu.usbserial-0001 115200\n# macOS (J-Link Serial over USB)\npython3 -m serial.tools.miniterm /dev/cu.usbmodem0009790147671 115200\n# Linux\npython3 -m serial.tools.miniterm /dev/ttyUSB0 115200\n```\n\n## Primitive Words\nThis minimal selection of primitive words is used to bootstrap the Forth system.\n\n| Word   | Stack Effects | Description                                   |\n| ------ | ------------- | --------------------------------------------- |\n| `:`    | ( -- )        | Start the definition of a new secondary word  |\n| `;`    | ( -- )        | Finish the definition of a new secondary word |\n| `@`    | ( addr -- x ) | Fetch memory contents at addr                 |\n| `!`    | ( x addr -- ) | Store x at addr                               |\n| `sp@`  | ( -- sp )     | Get pointer to top of data stack              |\n| `rp@`  | ( -- rp )     | Get pointer to top of return stack            |\n| `0=`   | ( x -- flag ) | -1 if top of stack is 0, 0 otherwise          |\n| `+`    | ( x y -- z )  | Sum the two numbers at the top of the stack   |\n| `nand` | ( x y -- z )  | NAND the two numbers at the top of the stack  |\n| `key`  | ( -- x )      | Read ASCII character from serial input        |\n| `emit` | ( x -- )      | Write ASCII character to serial output        |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheandrew168%2Fderzforth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheandrew168%2Fderzforth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheandrew168%2Fderzforth/lists"}