{"id":21828972,"url":"https://github.com/kyuvi/lrv-asm","last_synced_at":"2025-03-21T12:41:23.761Z","repository":{"id":170460692,"uuid":"415923033","full_name":"Kyuvi/lrv-asm","owner":"Kyuvi","description":"RISC-V assembler in Common Lisp","archived":false,"fork":false,"pushed_at":"2022-08-19T18:13:36.000Z","size":184,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-26T08:41:56.787Z","etag":null,"topics":["assembler","assembly","common-lisp","lisp","longan-nano","risc-v","risc-v-assembly"],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","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/Kyuvi.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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-10-11T12:47:02.000Z","updated_at":"2023-07-21T04:36:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"54e47b27-90c9-4eaa-82c0-aa6ff34b9e09","html_url":"https://github.com/Kyuvi/lrv-asm","commit_stats":null,"previous_names":["kyuvi/lrv-asm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kyuvi%2Flrv-asm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kyuvi%2Flrv-asm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kyuvi%2Flrv-asm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kyuvi%2Flrv-asm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kyuvi","download_url":"https://codeload.github.com/Kyuvi/lrv-asm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244800341,"owners_count":20512447,"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":["assembler","assembly","common-lisp","lisp","longan-nano","risc-v","risc-v-assembly"],"created_at":"2024-11-27T18:19:31.347Z","updated_at":"2025-03-21T12:41:23.740Z","avatar_url":"https://github.com/Kyuvi.png","language":"Common Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"#+TITLE: (Common) Lisp RISC-V assembler (lrv-asm)\n# #+STARTUP: content\n\nThe main repository is on [[https://codeberg.org/Kyuvi/lrv-asm.git][Codeberg]]. if you are viewing this anywhere else, it is just a mirror. Please use the [[https://codeberg.org/Kyuvi/lrv-asm.git][Codeberg]] repository for pull requests and issues. Thank you.\n\n* Description\nA crude but functional implementation of a dynamic [[https://en.wikipedia.org/wiki/Riscv][RISC-V]] assembler in [[https://en.wikipedia.org/wiki/Common_Lisp][Common Lisp]], Still in a pre-alpha state, pretty much everything is liable to change. Written and tested in [[https://gitlab.com/embeddable-common-lisp/ecl/][Embeddable Common Lisp]] and output code has only been created for and tested on the [[https://www.seeedstudio.com/Sipeed-Longan-Nano-RISC-V-GD32VF103CBT6-Development-Board-p-4205.html][Longan nano development board]]. I have tried to make it portable but I have not tested it properly on other Common Lisp implementations.\n\nIt currently supports only the 32-bit I and M modules plus the base instructions from the C module and the CSR module including the (proposed?) 32-bit CSR memory map, but has been designed to be extended to support other modules and both 64-bit and 128-bit instruction sets as well.\n\nThese are actually the basic modules/packages to be used to build up an assembler for the instruction set of a processor when needed.\n\nIt is not optimized for using compressed instructions, and when using the \"I-C-32-RV\" module, unless compressed instructions are explicitly used, the compressed instructions are only used for resolved immediates (labels), i.e. compressed instructions will only be used for backward branches if possible.\n\n* Syntax and Notation\n** Assembly Related\nIt includes some changes to the standard assembly notation and syntax namely....\n- pait - 4-bit   (nibble)\n- byte - 8-bit   (byte)\n- jait - 16-bit  (half word)\n- vait - 32-bit  (word)\n- zait - 64-bit  (double word)\n- yait - 128-bit (quad word)\n\nThough I will probably use Double and Quad for the floating point module names as the module letters are derived from those.\n\nalso sv/lv (store vait/load vait) are of the form....\n- (sv rs rb imm) ;; sv source-reg base-reg immediate\n- (lv rd rb imm) ;; lv dest-reg base-reg immediate\n\nas are all the other loads and stores (sb,lb, sj/lj, sz/lz).\n\nI personally find it easier to think like this about (modern) assembly code.\n\n** Common Lisp Related\nI shadowed \"and\", \"or\", (in the I-C-32-lrv module), \"not\" (in the rvi-derived module)  and rem (in the Multiplication module) so one can either shadow them when importing or use cl:and, cl:or etc in code.\n\nTwo new reader macros have been added namely, \"#h\" and \"#y\" for Twos complement hexadecimal and binary numbers respectively. They (should) act like hexadecimal and binary notations in other assemblers using the most significant bit of the register-length (i.e. bits 31 or 63) as the sign bit and can also be negated (i.e. #h-num = (- num), so #h-ffffffff = 1). This should avoid some issues with register-length immediate loads, i.e load immediate (li rd imm32), load address (la rd imm32) etc, and also help with optimisation.\n\nWhile in Common Lisp the notation =+constant+= is sometimes used for constants, I just added a phi symbol to the end to represent constants i.e. =constantΦ=, it turns out there are a lot of constants in the RISC-V ISA (see ./lrv-ins/csr-lrv.cl).\n\n* Installation and Use\nThis depends on having (Embeddable) Common lisp installed on the computer already.\n\nDue to time, personal and design reasons (the design is nowhere near complete as only a fraction of the modules have been finished and I am still learning about the RISC-V ISA and how it is used in implementations), this has not been packaged with ASDF, so the files need to be loaded into a lisp environment in order and a new package made using the right modules to target a particular processor.\n\nA simple example targeting the longan development board from a file in the top level i.e. the same level as this README.org. A position adjusted version of this example can be found in the examples folder.\n-----\n#+BEGIN_SRC lisp\n\n(in-package cl-user)\n\n(load \"./lrv-korr/packages.lisp\")\n(load \"./lrv-korr/env-lrv.cl\")\n(load \"./lrv-korr/kone-lrv.cl\")\n(load \"./lrv-korr/fmt-lrv.cl\")\n(load \"./lrv-korr/files-lrv.cl\")\n(load \"./lrv-korr/lrv-utils/clrv-utils.cl\")\n\n(load \"./lrv-ins/I-lrv.cl\")\n(load \"./lrv-ins/C-lrv.cl\")\n(load \"./lrv-ins/I-C-lrv.cl\")\n(load \"./lrv-ins/rvi-derived.cl\")\n(load \"./lrv-ins/M-lrv.cl\")\n(load \"./lrv-ins/csr-lrv.cl\")\n\n\n(defpackage \"LONGAN\"\n  (:use :cl :rvasm :clrv :c32 :i32 :ic32 :rdv :m32 :csr :csr32)\n  ;; beqz, bnez inc and dec  also defined in rvdrv.\n  (:shadowing-import-from :ic32 and or beqz bnez inc dec )\n  (:shadowing-import-from :m32 rem )\n  (:shadowing-import-from :rdv not ))\n\n(in-package :longan)\n\n;; set up processor specific environment with code starting at address 0\n\n(defparameter *env* (make-instance 'basic-env :address 0))\n\n(defparameter *max-address* (* 128 1024)) ;; longan internal flash is 128kb\n\n\n;; This can then be used as the actual assembler\n;; for the bumblebee core in the GD32V-IMAC SOC on the longan development board.\n\n;; =code starts here=\n(addi 'x1 'x0 #h20)  ;; load 20 into register x1\n\n\n;; set output file\n(setf (bin-file \"path/to/output-file.bin\") (link *env*))\n\n#+END_SRC\n-----\n\n# This can then be used as the actual assembler for the bumblebee core in the GD32-IMAC SOC on the longan development board.\n\n* Plans and Goals\n** Goals\n- Simple clear code using the expressiveness of (common) lisp.\n- Modular code to mirror the modularity of the RISC-V instruction set Architecture.\n- Concise and fast machine code output.\n # - Modularity.\n- Upload output file to development board from lisp environment(REPL) on Linux, iOS and Windows.\n- Simplified/Minimalised assembly syntax (no parenthesis or quotes)\n- Include remaining finalized RISC-V instruction modules.\n- 64-bit.\n- Automate building an assembler for a specific processor based on specified modules\n\n** Long term Goals\n- 128-bit.\n- ASDF build system and quicklisp (after design stabilization).\n- All RISC-V instruction modules including those not yet finalized\n\n** Non Goals\n- Speed of assembly/compiling process.\n- Targeting Multiple Instruction Set Architectures (though env-lrv.cl could be used for this with some expansion).\n \n* TODO\n- [ ] Edit/Add readtable to accept assembly syntax without parenthesis, quotes, set-label and label (while still allowing parenthesis for complex expressions?).\n- [ ] Add built in DFU (Device Firmware Upgrade) utility (using libusb?) that can be called from the REPL.\n- [ ] Optimize compiler (env-lrv.cl) for optional compressed instruction set use automatically (and clearly).\n- [ ] Include in and Optimize for optional floating point instruction sets automatically (and clearly) in Engine (kone-lrv.cl) or separate file.\n- [ ] Include all finalized RISC-V modules.\n- [ ] Include 64-bit instruction set in modules.\n- [ ] Automate building an assembler for a specific processor based on specified modules.\n- [ ] Include 128-bit instruction set in modules.\n\n* Acknowledgments\nThis assembler is based on\n- Andy Hefner's [[https://github.com/ahefner/asm6502][asm-6502]], https://ahefner.livejournal.com/20528.html.\n- Technoblogy's [[https://github.com/technoblogy/lisp-riscv-assembler][RISC-V assembler]], http://www.ulisp.com/show?310Z.\n\nAlso thanks to\n- [[https://github.com/dkochmanski][Daniel Kochmanski]]\n- Andrew Dailey's [[https://github.com/theandrew168/bronzebeard][Bronzebeard project]].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkyuvi%2Flrv-asm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkyuvi%2Flrv-asm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkyuvi%2Flrv-asm/lists"}