Kaya Çelebi
Home About GitHub PyPI Contribute Contact

Toolkit

Follow @kcelebi Star Watch

Let's check out how to use Toolkit. Toolkit contains functions that can be used to interpret specific lines, calculate jumps, and other debugging tools. First, let's import the class and functions:

from riscv_assembler.utils import *

Some of these functions rely on the class, some do not. First, let's look at those that rely on the Toolkit class. Let's instantiate an object:

tk = Toolkit()

No parameters required. Let's now look at some functions.

Instruction Format Function

This package also offers instruction format-specific functions for individual lines of assembly. The instruction types supported are R, I, S, SB, U, and UJ. The machine code is returned as a bitstring that can be printed to console. Check out the examples below for each instruction type:

R Type

This functions converts individual lines of assembly with R type instructions to machine code. The function usage is:

R_type(operation, rs1, rs2, rd)
Here is an example of translating add x0 s0 s1.
tk = Toolkit()
instr = tk.R_type("add","x0","s0","s1") #convert the instruction

print(instr) #print the bitstring

Note that the registers are being written as strings. The package maps them correctly to their respective binary values (ex. s0 maps to x8).

I Type

This functions converts individual lines of assembly with I type instructions to machine code. The function usage is:

I_type(operation, rs1, imm, rd)

Here is an example of translating addi x0 x0 32.

tk = Toolkit()
instr = tk.I_type("addi", "x0", "32", "x0") #convert the instruction

print(instr) #print bitstring

Note that the immediate is a string, not just a number. This was implemented this way for seamless integration with the convert() function, there is an easy workaround for using it on its own.

S Type

This functions converts individual lines of assembly with S type instructions to machine code. The function usage is:

S_type(operation, rs1, rs2, imm)

Here is an example of translating sw x0 0(sp).

tk = Toolkit()
instr = tk.S_type("sw", "x0", "sp", "0") #convert the instruction

print(instr) #print bitstring

Debugger Function

hex() converts an inputted string of binary to 32-bits in hexadecimal. There is an option to maintain leading zeros or not. The function usage is:

tk = Toolkit()
string = '00000000000000000000111100110011'

print(tk.hex(string,leading_zero=True)) #outputs '0x00000F33'
print(tk.hex(string,leading_zero=False)) #outputs '0xF33'

nibbleForm() takes an inputted string of unbroken binary and outputs it in nibbles separated by an inputted delimeter. The function usage is:

string = '00000000000000000000111100110011'

print(nibbleForm(string, delim = '\t'))
#outputs separed by tabs '0000 0000 0000 0000 0000 1111 0011 0011'

print(nibbleForm(string, delim = 'qqq')
#outputs '0000qqq0000qqq0000qqq0000qqq0000qqq1111qqq0011qqq0011'

calcJump() takes in a filename, a name of a function to jump to, and the line number of a branch statement to calculate the branch jump immediate. The line number should not just be the line number in your text editor; ignore empty lines, comments, and lines that indicate the start of a function (such as loop:). Consider the first valid line as line 0. The function usage is:

tk = Tookit()

print( tk.calcJump(filename = "myfile.s", x = 'loop', line_num = 42)
#outputs an immediate according to how many instructions
#need to be jumped to get to the function

For functions that do not exist in the system that are used often, feel free to contact me to have it implemented. Most functions are readily available, however, with a growing library it is possible that a pseudo instruction or two slipped past. I intend on implementing functions that allow for the user to bypass any shortfalls like this.