Skip to content

jedSavage/Slexip

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

41 Commits

image

image

 
 

shields

shields

 
 

LICENSE

LICENSE

 
 

README.md

README.md

 
 

Repository files navigation

SLEXIP

Note: this project is currently in a conceptual phase - it is just an idea. No interpreter nor compiler have been made yet. Suggestions and requests to the specifications are welcome and encouraged. Please submit ideas/feedback/suggestions as issues.

SLEXIP is a low level programming language inspired by Piet and the 6502 microprocessor. It is not as esoteric as Piet is but it does represents code visually as pixels and allows the execution of code in different directions across the image.

Program Data Representation

Programs for SLEXIP are written using GIF (index) images. The GIF should contain 256 indices/colors and can be any size up to the maximum limited by GIF standard (65535 x 65535); however, only the first 64k pixels are addressable. The colors chosen for each index do not matter for program execution but can be modified by the program during execution.

SLEXIP uses the image as memory in addition to program data. As the program runs, altering data in memory directly alters the image. There is no console output - altering memory is the standard way of outputting data in SLEXIP.

Numerical Representation

Throughout this document a $ character before any value denotes hexadecimal. For decimal values no symbol will be used ($1F vs 31) and binary values will be represented with a postfix b (e.g. 00110110b). Negative numbers (signed bytes) are represented with a minus sign preceding them (-127). It is up to your program to interpret data as signed or unsigned.

Memory

Pixels are addressable using 2-byte words. The first pixel (pixel index 0) is located at $0000. Pixel addresses increase by 1 running from left to right. Addresses wrap around to the next line of pixels. In a 10x10 image, the last pixel on the 3rd line is $001D; the 1st pixel on the 4th line is $001E; and the last pixel on the last line is $0063.

Example of 10x10 Image

Each pixel can represent a value from 0 to 255 (1-byte). This value also denotes the color index which that pixel should be displayed with. Operators are 1-byte long and Memory addresses are 2-bytes (16-bits) long. Some operators do not require additional data (operands), others may require a value and/or memory address which will be fetched from the pixel(s) following the operator. The combination of operator and operand is an Instruction. For example: $40 $42 $04 $B5 is a 4-byte instruction that copies (CVM in Direct Mode or $40) the value of $42 into memory address $04B5.

Program Initialization.

After loading a program (image) into memory, the interpreter caches the values contained in the first 18 pixel locations. These pixels contain pointers to various memory addresses that will be used by the interpreter during program execution. Since memory addresses are 16-bits wide, each pointer takes up 2 pixels. The only way to change the cached locations after initialization is to write the new values to the initialization addresses and execute a reset ($FF or RST) operation.

Note that the values in these locations are pointers to memory addresses not the memory addresses themselves (unless of course they point to themselves). These pixels can be changed immediately upon program execution as the values are cached before any code is executed. Once cached, the interpreter beings executing code starting the the address stored in the Program Counter (PC).

Initialization Pointers

Pixels $0000, $0001 - Clock-Speed Register Initialization Pointer

The first pixel in the image contains the memory location of the clock-speed register (CS-Register). This is a 24-bit register that the interpreter sets its speed by. A value of 0 halts program execution (if interpreter has debugging capabilities, manual stepping can be done). A value of 1 means to evaluate 1 pixel per second (useful for debugging). A value of 60 means to step through 60 pixels per second (60hz). Max value is 16777215 ($FFFFFF) or approx 16.7mhz. The value at the location pointed to can be changed during program execution to change interpreter speed.

Pixels $0002, $0003 - Stack-Pointer Initialization Pointer

This pixel contains the memory location of the stack-pointer (SP). The SP is a 16-bit pointer containing the memory location of the top of the stack. The stack can be relocated during code execution by changing the values at the SP. The stack grows backwards: when a value is pushed to the stack, the pointer value decrements by one; when a value is popped from the stack the pointer value is increased by one.

Pixels $0004, $0005 - Input-Key Register Initialization Pointer

This pixel contains the memory location of the Input-Key Register (IK-Register) - an 8-bit register whose lower 7-bits contain ascii key code of the last key pressed. Bit-7 of this register is set when a non-modifier key is pressed down. This register is updated each clock cycle.

Pixels $0006, $0007 - Modifier-Key Register Initialization Pointer

This pixel contains the memory location of the Modifier-Key Register (MK-Register). an 8-bit register with the following bits set when the appropriate key is being pressed down. Bits are cleared as soon as the key is released. This register is updated each clock cycle.

Bit Position Modifier Key
Bit 0 Up Arrow
Bit 1 Down Arrow
Bit 2 Left Arrow
Bit 3 Right Arrow
Bit 4 Shift
Bit 5 Control
Bit 6 Alt
Bit 7 Command

Pixels $0008, $0009 - LFSR Initialization Pointer

This pixel contains the memory location of a 16-bit Linear Feedback Shift Register (LFSR) with taps at bits 15, 13, 12, and 10. The LFSR progresses to its next state once after every access. Changing the LFSR value to anything other than zero seeds the LFSR with that value and advances to the next state. Placing a value of $0000 into the register effectively turns the LFSR off.

16-Bit LFSR

The last 2 bits of the SD-Register affect the behavior of the LFSR.

Pixels $000A, $000B - Program-Counter Initialization Pointer

This pixel contains the memory location of the program-counter (PC). The PC is a 16-bit pointer that contains the memory address of the next operator to be evaluated. The value here is automatically incremented/decremented depending on the sd-register and the instruction being evaluated. Writing a value to the program counter will change where the next instruction will be read from, though the instruction of writing will itself modify the register after the write takes place.

Pixels $000C, $000D - Status/Direction Register Initialization Pointer

This pixel contains the memory location of the status/direction register (SD-Register). Bits 0-3 contain the status flags. Bit-0 is the Carry flag (C), Bit-1 is the Zero flag (Z), Bit-2 is the Overflow flag (V), bit-3 is the Negative flag (N). Though you can write to these bits directly, they are usually changed by operators.

Bit Position Description
Bit-0 Carry Flag
Bit-1 Zero Flag
Bit-2 Overflow Flag
Bit-3 Negative Flag

Bits 4-5 of this register contain the direction the program is currently evaluating in. With the default value of 00, the PC increments by 1 each clock cycle, rolling over at the end of the image. These bits also affect how indexing is applied.

Bits 4 & 5 Program Direction PC Change per Clock Additional at Rollover
00b Right + 1 None
01b Down + CW-Register + 1
10b Left - 1 None
11b Up - CW-Register - 1

Bits 6 and 7 are used to control the behavior of the LFSR. If bit-6 is set, the taps are mirrored so that the output progresses in the reverse order. Bit 7 controls how often the LFSR progresses to the next output. When clear, the LFSR progresses once after each read or write access; when set, the LFSR progresses once per clock tick.

Bit 6 State LFSR Direction
0b Normal (Forward)
1b Mirrored (Reverse)
Bit 7 State LFSR Progression Behavior
0b Once after each read or write access
1b Once every clock tick

Pixels $000E, $000F - Canvas-Width Register Initialization Pointer

This pixel contains the memory location of the canvas-width Register (CW-Register). The CW-Register holds a 16-bit value representing the width of the canvas in pixels. Changing the value at the CW-Register will dynamically change the width of the canvas. New pixels will be added with a default value of $EE. Clipped pixels will be permanently lost. The interpreter will update the displayed image as needed. Note that new pixels are added or removed from the end of memory, which can result in the image being distored after resizing.

Pixels $0010, $0011 - Canvas-Height Register Initialization Pointer

This pixel contains the memory location of the canvas-height Register (CH-Register), which work similarly to the CW-Register.

Memory Addressing Modes

There are seven modes that can be used with operators. Not all modes are available with all operators.

Implied (IM)

In implied mode, the data and/or memory that the operator works with is implied resulting in single-byte instructions. Status operators, for example, work solely on the bits of the status register.

Non-Indexed

Relative (R)

This mode is only available with branch operators. The number provided to the operator is added to current PC and program execution continues from that address. Only one byte is passed and it is a signed byte. This allows a jump of -128 to +127 bytes relative to the current program counter.

BCC -50 ; If Carry flag is Clear, Branch back 50 bytes/pixels.

Direct (D)

Uses the value directly as entered. Example, using the JMP operator in direct mode, the PC is set to the value provided and program execution continues from that address.

JMP $2A00 ; Jump to memory location $2A00 (Pixel 10752)

Indirect (I)

Fetches the value from the provided memory address, and uses that value with the operator. Example, using the JMP operator in indirect mode: JMP $44 $02 - fetches the value from memory address $4402 and sets the PC to that value.

JMP ($2A00) ; Fetch value from memory location $2A00 & $2A01 and jump to that location.

Indexed

Indexing follows the same rules as the program counter according to bits 4 & 5 of the SD-Register.

Direct Indexed (DX)

The value at the index location is added to the value provided. The sum is then used in the operation.

ADC $0080, $0100, $0090 ; Offset value at $0090. Add value at memory location $0100+offet to value at memory $0080+offset. Store result at memory $0080+offset.

Indexed Indirect (XI)

The value at the index location is added to the memory address provided. The value at the new location is then used in the operation.

Indirect Indexed (IX)

The value at the memory location is fetched and the value at the index location is added to it. The sum is then used in the operation.

Instruction Set:

There are 64 operators. The chart below shows their op-codes. All other opcodes are interpreted as NOP instructions. Program Counter offsets listed are based upon the Direction Register bits being set to 00b. For other direction configurations, see Direction Register.

Data Transport operators

$XX = 1-Byte Op-Code
VAL = 1-Byte Value

Memory addresses are 16-bits wide. Instruction use a high-byte followed by a low-byte to specify an address.
MEM2-HB = Target Memory High Byte
MEM2-LB = Target Memory Low Byte

MEM1-HB = Source Memory High Byte
MEM1-LB = Source Memory Low Byte

Indexes are also memory addresses. The value at the address contains the index offset. IND-HB = Index Memory High Byte
IND-LB = Index Memory Low Byte
Where two memory addresses are used in an indexed mode, indexing applies to both source and target address.

CVM Flags: [-Z-N--]
Copy a value into memory.

Addressing Mode Instruction Format PC Offset
Direct 40 VAL TMEM-HB TMEM-LB +4
Indirect 60 VAL TMEM-HB TMEM-LB +4
Direct Indexed C0 VAL TMEM-HB TMEM-LB IND-HB IND-LB +6
Indexed Indirect 80 VAL TMEM-HB TMEM-LB IND-HB IND-LB +6
Indirect Indexed A0 VAL TMEM-HB TMEM-LB IND-HB IND-LB +6

CMM Flags: [-Z-N--]
Copy from first memory address to the second.

Addressing Mode Instruction Format PC Offset
Direct 41 MEM1-HB MEM1-LB MEM2-HB MEM2-LB +5
Indirect 61 MEM1-HB MEM1-LB MEM2-HB MEM2-LB +5
Direct Indexed C1 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7
Indexed Indirect 81 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7
Indirect Indexed A1 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7

Arithmetic operators

ADC Flags: [CZVN--]
Add (with carry) two memory values, replacing the first location with result. Indexed modes apply to the second memory address.

Addressing Mode Instruction Format PC Offset
Direct 42 MEM1-HB MEM1-LB MEM2-HB MEM2-LB +5
Indirect 62 MEM1-HB MEM1-LB MEM2-HB MEM2-LB +5
Direct Indexed C2 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7
Indexed Indirect 82 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7
Indirect Indexed A2 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7

SBC Flags: [CZVN--]
Subtract (with borrow) two memory values, replacing the first memory location with result. The second memory value gets subtracted from the first. Indexed modes apply to the second memory address.

Addressing Mode Instruction Format PC Offset
Direct 43 MEM1-HB MEM1-LB MEM2-HB MEM2-LB +5
Indirect 63 MEM1-HB MEM1-LB MEM2-HB MEM2-LB +5
Direct Indexed C3 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7
Indexed Indirect 83 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7
Indirect Indexed A3 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7

INC Flags: [-Z-N--]
Increment Memory by one.

Addressing Mode Instruction Format PC Offset
Direct 45 TMEM-HB TMEM-LB +3
Direct Indexed C5 TMEM-HB TMEM-LB IND-HB IND-LB +5

DEC Flags: [-Z-N--]
Decrement Memory by one.

Addressing Mode Instruction Format PC Offset
Direct 44 TMEM-HB TMEM-LB +3
Direct Indexed C4 TMEM-HB TMEM-LB IND-HB IND-LB +5

Status operators

CLC Flags: [C------]
Clear the carry flag.

Addressing Mode Instruction Format PC Offset
Implied E0 +1

SEC Flags: [C------]
Set the carry flag.

Addressing Mode Instruction Format PC Offset
Implied E1 +1

CLVFlags: [--V----]
Clear overflow flag.

Addressing Mode Instruction Format PC Offset
Implied F0 +1

Logical operators

AND Flags: [-Z-N--]
Logical AND two memory locations, replacing the first memory location with result.

Addressing Mode Instruction Format PC Offset
Direct 50 MEM1-HB MEM1-LB MEM2-HB MEM2-LB +5
Direct Indexed D0 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7

ORM Flags: [-Z-N--]
Logical OR two memory locations, replacing the first memory location with result.

Addressing Mode Instruction Format PC Offset
Direct 51 MEM1-HB MEM1-LB MEM2-HB MEM2-LB +5
Direct Indexed D1 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7

XOR Flags: [-Z-N--]
Logical XOR two memory locations, replacing the first memory location with result.

Addressing Mode Instruction Format PC Offset
Direct 52 MEM1-HB MEM1-LB MEM2-HB MEM2-LB +5
Direct Indexed D2 MEM1-HB MEM1-LB MEM2-HB MEM2-LB IND-HB IND-LB +7

SHL Flags: [CZ-N--]
Shifts all bits of a memory location left one position. 0 is shifted into bit-0 and the original bit-7 is shifted into the Carry.

Addressing Mode Instruction Format PC Offset
Direct 53 MEM2-HB MEM2-LB +5
Direct Indexed D3 MEM2-HB MEM2-LB IND-HB IND-LB +7

SHR Flags: [CZ-N--]
Shifts all bits of a memory location right one position. 0 is shifted into bit-7 and the original bit-0 is shifted into the Carry.

Addressing Mode Instruction Format PC Offset
Direct 54 MEM2-HB MEM2-LB +5
Direct Indexed D4 MEM2-HB MEM2-LB IND-HB IND-LB +7

ROL Flags: [CZ-N--]
Shifts all bits of a memory location left one position. The Carry is shifted into bit 0 and the original bit 7 is shifted into the Carry.

Addressing Mode Instruction Format PC Offset
Direct 55 MEM2-HB MEM2-LB +5
Direct Indexed D5 MEM2-HB MEM2-LB IND-HB IND-LB +7

ROR Flags: [CZ-N--]
Shifts all bits of a memory location right one position. The Carry is shifted into bit 7 and the original bit 0 is shifted into the Carry.

Addressing Mode Instruction Format PC Offset
Direct 56 MEM2-HB MEM2-LB +5
Direct Indexed D6 MEM2-HB MEM2-LB IND-HB IND-LB +7

Branch operators

VAL = 1-Byte Offset Value (Signed).

BCC Flags: [------]
Branch on carry clear - Branch to address if the carry flag is clear. (Increments the PC by VAL).

Addressing Mode Instruction Format PC Offset
Relative 20 VAL +2 | VAL

BCS Flags: [------]
Branch on carry set - Branch if the carry flag is set.

Addressing Mode Instruction Format PC Offset
Relative 21 VAL +2 | VAL

BNE Flags: [------]
Branch on non-zero - Branch if the zero flag is clear.

Addressing Mode Instruction Format PC Offset
Relative 22 VAL +2 | VAL

BEQ Flags: [------]
Branch on zero - Branch if the zero flag is set.

Addressing Mode Instruction Format PC Offset
Relative 23 VAL +2 | VAL

BPL Flags: [------]
Branch on positive - Branch if the negative flag is clear.

Addressing Mode Instruction Format PC Offset
Relative 24 VAL +2 | VAL

BMI Flags: [------]
Branch on negative - Branch if the negative flag is set.

Addressing Mode Instruction Format PC Offset
Relative 25 VAL +2 | VAL

BVC Flags: [------]
Branch on overflow clear - Branch if the overflow flag is clear.

Addressing Mode Instruction Format PC Offset
Relative 26 VAL +2 | VAL

BVS Flags: [------]
Branch on overflow set - Branch if the overflow flag is set.

Addressing Mode Instruction Format PC Offset
Relative 27 VAL +2 | VAL

Comparison Operators

CMP Flags: [CZ-N--]
Compare two Memory locations. Sets zero flag if values are identical. Sets carry flag if the first Memory value is equal to or greater than the second Memory value.

Addressing Mode Instruction Format PC Offset
Direct 46 TMEM-HB TMEM-LB +3
Indirect 66 TMEM-HB TMEM-LB +3
Direct Indexed C6 TMEM-HB TMEM-LB IND-HB IND-LB +5
Indexed Indirect 86 TMEM-HB TMEM-LB IND-HB IND-LB +5
Indirect Indexed A6 TMEM-HB TMEM-LB IND-HB IND-LB +5

Program Control

JMP Flags: [------]
Set PC to new value, altering flow of program.

Addressing Mode Instruction Format PC Offset
Direct 5F TMEM-HB TMEM-LB Set to Memory
Indirect 6F TMEM-HB TMEM-LB Set to Value at Memory

JSR Flags: [------]
Jump sub routine. Pushes the address of the next operator to the stack, then sets the PC to a new Memory value.

Addressing Mode Instruction Format PC Offset
Direct 4F TMEM-HB TMEM-LB Set to Memory

RSR Flags: [------]
Return from subroutine, pop the stack value into the PC and continues evaluating from there.

Addressing Mode Instruction Format PC Offset
Implied EF Set to Value from Stack

Stack operators

PHS Flags: [-Z-N--]
Push Memory to stack.

Addressing Mode Instruction Format PC Offset
Direct 4A TMEM-HB TMEM-LB +3

PHS Flags: [------]
Push status to stack.

Addressing Mode Instruction Format PC Offset
Implied FA +1

PLM Flags: [-Z-N--]
Pop from stack into Memory locaton.

Addressing Mode Instruction Format PC Offset
Direct 4B TMEM-HB TMEM-LB +3

PLS Flags: [CZVN--]
Pop from stack into status register.

Addressing Mode Instruction Format PC Offset
Implied FB +1

Reset

RST Flags: [CZVNDD]
Reset - Runs the interpreter's initialization routine, resets all cached references to pointers.

Addressing Mode Instruction Format PC Offset
Implied FF N/A

GIF Index operators

IVAL = 1-Byte Index
RVAL = 1-Byte Red Value
GVAL = 1-Byte Green Value
BVAL = 1-Byte Blue Value

IDX Flags: [------]
Index Color Modifier - Instructs the interpreter to change the color of an index.

Addressing Mode Instruction Format PC Offset
Direct 5E IVAL RVAL GVAL BVAL +5

Null operators

NOP Flags: [------]
No operator - Does nothing.

Addressing Mode Instruction Format PC Offset
N/A All Other Op-Codes +1

Operator Evaluation Cycle

  1. Operator is fetched from the memory location reference by the PC.
  2. Depending on the operator, the operands are fetched from the memory following the operator.
  3. The full Instruction is evaluated, and any related memory is read from and written to.
  4. The flags of the status-register are updated to reflect the operation.
  5. The PC is incremented/decremented as neccesary depending on SD-Register bits 4 and 5, and the length of the instruction, see Direction Register.
  6. The LFRS is cycled the same amount as the instruction length.
  7. The CS-Register is read and the interpreter speed is adjusted if needed.
  8. The IK-Register and MK-Register are both updated, depending on the keys currently pressed.
  9. The CW-Register and CH-Register are read and the image size displayed is adjusted if needed.

About

No description, website, or topics provided.

Resources

Readme

License

GPL-3.0 license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published