Forums - Open Redstone Engineers
JISA: Jallenator Instruction Set Assembler - Printable Version

+- Forums - Open Redstone Engineers (https://forum.openredstone.org)
+-- Forum: ORE General (https://forum.openredstone.org/forum-39.html)
+--- Forum: Projects & Inventions (https://forum.openredstone.org/forum-19.html)
+---- Forum: In Progress (https://forum.openredstone.org/forum-20.html)
+---- Thread: JISA: Jallenator Instruction Set Assembler (/thread-5756.html)

Pages: 1 2 3

JISA: Jallenator Instruction Set Assembler - Jallen - 02-09-2015

JISA: An easy to use custom instruction set assembler
*UPDATED*
Repo link
*UPDATED*
Prepare for incoming update on the tutorial.

Disclaimer: This post is subject to changes as is the script itself. I will try my best to keep the documentation as up to date as possible but it may not always be right on time.

Overview

JISA is a python script that takes a .yaml file (default name IS.yaml) that describes your instruction set and will then be able to assemble any code written in your assembly language into either a hex or a binary format. Both the source and the output file must be in a plain text format.

Requirements:
  • Python 3.* Installed
  • PyYaml package (see requirements.txt in the repo for link)


Constructing your .yaml file

The first thing you must do is have an instruction set. I'll be creating various instructions to demonstrate the way you lay it out.
Within the .yaml file it is important to label everything with bit widths so that the assembler knows how much to fill. It is important to start the file and separate sections with '---' so the script knows where to start.

The .yaml file is constructed of three sections:
  • Formats
  • Instructions
  • Custom arguments
Formats
In this section you define the bit layout of various different types of instruction.
For example: Say I wanted to layout the format for a simple two operand logic type instruction. I am going to have a 4 bit op code for this IS so I must state that the op code will take up 4 bits explicitly:

Code:
---
RR;16:
    - op;4

As you can see, I have also defined the line length in the declaration. RR(Register, Register) will be the format for any instruction that takes two operands and has an op code. However we haven't finished defining the entire format. We have to ensure that the sum of the bit widths of the constituent parts is equal to the total line length.

Code:
---
RR;16:
    - op;4
    - r;3
    - r;3
    - 0;6

We have now completed our first basic format. As you can see I have used 3 different types of predefined argument types (op, r, 0) there are 6 total predefined argument types:
  • op: op code
  • r: register argument
  • i: immediate (can be given in binary or hex(prefix with '0x' for hex))
  • var: forks the format based on what type of argument is provided
  • 0: ...it's a 0
  • 1: you guessed it!

Now the var argument probably needs a bit of explaining. It's probably easier to explain with an example. So let's change how the RR instruction works. Say I wanted to select between using either a second register or an immediate. I would do something like this:

Code:
---
RRI;16:
    - op;4
    - r;3
    - var;9
    - var:
        r:
            - r;3
            - 0;6
        i:
            - i;8
            - 1;1

I've used the final bit in the line as a signifier bit that decides whether or not our ISA uses an immediate or a register argument.
When you use the var argument type, you have to define the different types of arguments in the final element of the list. It must always be at the end of the format so that the assembler knows where to look for the forks. There are two different types of argument that have valid forks: r and i.
If one of these types of argument is found, the line format follows the corresponding fork.

Custom Arguments

'But Jallen!' I hear you cry 'What if I want to use an argument other than the ones you've already said?!' Well we can do that!
You need to use a custom argument. There are two stages to making a custom argument:
  1. Define
  2. Declare
To define a custom argument, you need to go to the third section of the .yaml file and define what values you can give. Let's use the example of a simple jump instruction. First we have to define it's format:

Code:
---
JMP;16:
    - op;4
    - ~cond;4
    - i;8
---
(see later for defining the instruction)
---
cond:
    'if0': '0001'
    '!if0': '0010'
    'Cout': '0011'
    '!Cout': '0100'
    'gt': '0101'
    'lt': '0110'
    'eq': '0111'
    '!eq': '1000'
...

In this I've both defined the custom argument and declared it. To declare it you must use the '~' symbol in the format followed by the tag and the bit width. In the definition you define the values the argument can take, you then define the binary value each one represents. It is important to use quotation marks so that the assembler treats it as a string rather than a number. It also allows for special character usage in the values your custom can take.

What this .yaml will allow for is a conditional jump instruction to an address specified by the 8-bit immediate and the condition can be any from the list.

Multi-line:

If you want to have a multi-line instruction, it's pretty simple to add it that in:
Code:
---
JMP;16,16:
    - op;4
    - ~cond;4
    - 0;8
    - i;16
---
===
---
cond:
    'if0': '0001'
    '!if0': '0010'
    'Cout': '0011'
    '!Cout': '0100'
    'gt': '0101'
    'lt': '0110'
    'eq': '0111'
    '!eq': '1000'
All you have to do is separate the line lengths for your two or more lines with a comma.

Defining Instructions

It's very simple to define an instruction. All you have to do is declare a keyword with a list of it's format tag and it's opcode. For instance:
Code:
[code]---
JMP;16,16:
    - op;4
    - ~cond;4
    - 0;8
    - i;16
---
jump:
    - JMP
    - '1000'
---
cond:
    'if0': '0001'
    '!if0': '0010'
    'Cout': '0011'
    '!Cout': '0100'
    'gt': '0101'
    'lt': '0110'
    'eq': '0111'
    '!eq': '1000'
Each instruction takes 2 values, the format and the opcode. Again it is important to use quotes for the opcode so the object is kept as a string.
This .yaml file will fully allow us to write a line like this:
Code:
jump !Cout 0xabc1

N.B. you must write the arguments in the order they are delcared in the format. I may add the ability to mix them up in the future but for now, that's how it is.

To use the script enter:
Code:
python <script_name>.py -h
This will show you what arguments you need to use and some other options too

If you have any suggestions or find a bug please leave a comment or find me ingame.

RE: JISA: Jallenator Instruction Set Assembler - Apocryphan - 02-09-2015

And suddenly I felt a big *whoosh* overhead, not my forte but the more i stare at it the more it sorta makes sense.

RE: JISA: Jallenator Instruction Set Assembler - Magic :^) - 02-09-2015

I read through this and it's really helpful Big Grin
I can't wait to implement my IS in this!

RE: JISA: Jallenator Instruction Set Assembler - LordDecapo - 02-09-2015

YES YES YES! A VERSION OF YOUR ASSEMBLER THAT I DONT HAVE TO GIVE YOU MY IS FOR !!! I CAN CONFIG MYSELZZZZZZZZ!!! Big Grin

RE: JISA: Jallenator Instruction Set Assembler - Jallen - 02-09-2015

(02-09-2015, 09:08 PM)LordDecapo Wrote: YES YES YES! A VERSION OF YOUR ASSEMBLER THAT I DONT HAVE TO GIVE YOU MY IS FOR !!! I CAN CONFIG MYSELZZZZZZZZ!!! Big Grin

That's the idea Tongue

RE: JISA: Jallenator Instruction Set Assembler - greatgamer34 - 02-09-2015

Awesome work man!

RE: JISA: Jallenator Instruction Set Assembler - Magic :^) - 02-10-2015

after this, I just have to parse my binary into ./autoprogram format and I'm all set! Big Grin

RE: JISA: Jallenator Instruction Set Assembler - Jallen - 02-10-2015

depending on the format of your PROM, it's pretty simple. I made one for IizR's prom. Also when you do make your .yaml file, can you send me a copy so I can put it in an examples folder in the repo (same goes for anyone making a .yaml file)

RE: JISA: Jallenator Instruction Set Assembler - LordDecapo - 02-10-2015

Sure,, but u need to look at the new IizR13 PROM... it's kinda diagnal. Lol so the coding for "next line" will be a tad more annoying. If you /warp IizR, then fly in the direction of the old IS board ull see in front Of you,... the new PROM and CPU Are out there... can't miss it, it's 256 lines of diagnal PROM

RE: JISA: Jallenator Instruction Set Assembler - Jallen - 02-10-2015

(02-10-2015, 12:34 PM)LordDecapo Wrote: Sure,, but u need to look at the new IizR13 PROM... it's kinda diagnal. Lol so the coding for "next line" will be a tad more annoying. If you /warp IizR, then fly in the direction of the old IS board ull see in front Of you,... the new PROM and CPU Are out there... can't miss it, it's 256 lines of diagnal PROM

Does it start at the top or somewhere else?