riscv-utils

 1# riscv-utils
 2
 3Scheme utility procedures for the [RISC-V][riscv website] instruction set architecture.
 4
 5## Features
 6
 7The feature set of provided procedures is centered around easing the
 8development of utilities for RISC-V (especially instruction set
 9simulators). Currently the following features are provided:
10
11* `decode.scm`: Decoding of RISC-V instructions.
12* `encode.scm`: Encoding of RISC-V instructions.
13* `convert.scm`: Conversion from/to different representations.
14* `opcodes.scm`: Constants for instruction opcodes (currently rv32i only).
15
16## Usage
17
18The code is supposed to be used from a Scheme REPL, no binaries are
19provided. The Scheme files in the `riscv/` directory are mostly(?)
20[R7RS][r7rs small] compatible. It should be possible to use them with any
21standard compliant Scheme implementation which provides an
22[SRFI-151][srfi-151] module. Just load the files you want to use
23using `(load "riscv/<file>.scm")` from your Scheme REPL.
24
25If your favorite Scheme implementation is [CHICKEN][call-cc], read on.
26
27### Example
28
29The API is intentionally very low-level. Nonetheless, many fun things
30can be done with it. The following example takes an existing `JAL`
31instruction (e.g. as extracted from a `riscv32-unknown-elf-objdump -d`
32output) and modifies it to jump somewhere else.
33
34	$ csi
35	> (import riscv)
36	> (set! jal #x0100056f)
37	> (instr-j-imm jal)
38	16
39	> (j-type (instr-opcode jal) (instr-rd jal) 32)
40	33555823
41
42The value `33555823` (`0x200056f`) is RISC-V machine code for a JAL
43instruction holing the value `32` (instead of `16`) as a J-immediate.
44This can be easily verified using:
45
46	> (set! jal-new 33555823)
47	> (instr->hex jal-new)
48	"#x200056f"
49	> (instr-j-imm jal-new)
50	32
51
52## Installation
53
54In addition to standard compliant(?) Scheme source code, this repository
55also contains the required files for using the code as a CHICKEN Scheme
56[egg][call-cc eggs]. However, since the code is still in very early
57stages of development I haven't published it as an egg yet. Nonetheless,
58an egg can be built locally using:
59
60	$ chicken-install -test
61
62### Building without installing
63
64If installation is not desired, build as follows:
65
66	$ export CHICKEN_REPOSITORY_PATH="$(pwd):${CHICKEN_REPOSITORY_PATH}"
67	$ chicken-install -n -test
68
69Afterwards simply run `(import riscv)` in `csi(1)` as usual.
70
71## License
72
73This program is free software: you can redistribute it and/or modify it
74under the terms of the GNU General Public License as published by the
75Free Software Foundation, either version 3 of the License, or (at your
76option) any later version.
77
78This program is distributed in the hope that it will be useful, but
79WITHOUT ANY WARRANTY; without even the implied warranty of
80MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
81Public License for more details.
82
83You should have received a copy of the GNU General Public License along
84with this program. If not, see <http://www.gnu.org/licenses/>.
85
86[riscv website]: https://riscv.org/
87[srfi-151]: https://srfi.schemers.org/srfi-151/srfi-151.html
88[r7rs small]: https://small.r7rs.org/
89[call-cc]: https://call-cc.org
90[call-cc eggs]: https://eggs.call-cc.org/