DGR2B - HackMD

# DGR2B This is an experimental firmware for the digirule 2. Full details about brad's Digirule project can be found here: [bradsprojects.com/digirule2](https://bradsprojects.com/digirule2/). It is not officially supported. You can use [DigiQt](https://github.com/wawachief/DigiQt) to test and debug your programs, since this instruction set is included by default. ## New instructions Following the notes from [Athanasios Anastasiou](https://dgtools.readthedocs.io/en/latest/instruction_set_notes.html) about the digirule instructions set, I have added some new instructions to the digirule. There is no change in the original instructions so you can use your old programs with this new instruction set. ### DR2U new instructions - **SWAPRA** swap RAM and accumulator (2 bytes - opcode ***35***) - **SWAPRR** swap RAM and RAM (3 bytes - opcode ***36***) - **MUL** unsigned 8-bit multiply (3 bytes opcode ***37***); on entry arg1 = multiplicand and arg2 = multiplier; on exit arg1 = product - **DIV** unsigned 8-bit divide (3 bytes - opcode ***38***); on entry arg1 = dividend and arg2 = divisor; on exit arg1 = quotient and accumulator = remainder As with other exceptions, divide-by-zero will halt the CPU. The status register is not affected by any of these instructions. ### Indirect copy - **COPYLI** *literal* *ref* (3 bytes - opcode ***224***): Copy a literal value to the address referenced in RAM location *ref* - **COPYAI** *ref* (2 bytes - opcode ***225***): Copy the accumulator to the address referenced in RAM location *ref* - **COPYIA** *ref* (2 bytes - opcode ***226***): Copy the content of the address referenced in RAM location *ref* to the accumulator(2 bytes). Zero flag affected (same way as COPYRA). - **COPYRI** *ram1* *ref2* (3 bytes - opcode ***227***): Copy the content of the address *ram1* to the address referenced in RAM location *ref2* (3 bytes). Zero flag affected (same way as COPYRR). - **COPYIR** *ref1* *ram2* (3 bytes - opcode ***228***): Copy the content of the address referenced in RAM location *ref1* to the address *ram2* (3 bytes). Zero flag affected (same way as COPYRR). - **COPYII** *ref1* *ref2* (3 bytes - opcode ***229***): Copy the content of the address referenced in RAM location *ref1* to the address referenced in RAM location *ref2* (3 bytes). Zero flag affected (same way as COPYRR). ### Shift operations with accumulator - **SHIFTAR** (1 byte - opcode ***230***): Shift the contents of the accumulator right (through the carry flag) by one (same way as SHIFTRR). - **SHIFTAL** (1 byte - opcode ***231***): Shift the contents of the accumulator left (through the carry flag) by one (same way as SHIFTRL). ### Indirect JUMP and CALL - **JUMPI** *ref* (2 bytes - opcode ***232***): Jump to the location referenced in RAM location *ref* and continue running instructions from there (same way as JUMP) - **CALLI** *ref* (2 bytes - opcode ***233***): Jump to the location referenced in RAM location *ref*, continue running instructions from there, then return once a 'RETURN' or 'RETLA' instruction is executed (same way as CALL) ### Conditional jumps - **jumpz** *pc* (2 bytes - opcode ***229***) : Jumps to *pc* location if Zero flag is set - **jumpnz** *pc* (2 bytes - opcode ***229***) : Jumps to *pc* location if Zero flag is not set these instructions are equivalent to ``` bcrsX 0 252 // X=c(jumpz) or s(jumpnz) jump pc ``` but only take two bytes instead of 5. ### Bit manipulation instructions - **BCHG** alias **TBR** *bit* *ram*(3 bytes - opcode ***233***) : Toggles *bit* in *ram* - **ANDLR**, **ANDRR**, **ORLR**, **ORRR*, **XORLR**, **XORRR** *arg1* *arg2* (3 bytes - opcode ***242-247***): same as original bit instructions (**ANDLA**, ...) except they apply to RAM (*arg2*) instead of the accumulator. ## The Software Stack The PIC microcontroler has enough RAM to store additionnal data, so I added a 256 bytes stack, called the software stack. You can use it as data storage or watever you want in your program. It is completely independant from the program counter stack used to CALL a subroutine. To use it, you have two new instructions : - **SSPUSH** (1 byte - opcode ***234***) : pushes the value stored in the accumulator into the operation stack. Halts the program execution in case of stack overflow. - **SSPOP** (1 byte - opcode ***235***) : pops one value out of the stack into the accumulator. Halts the program execution in case of stack underflow. Zero flag affected. - **SSPUSHR** *ram* (2 byte - opcode ***236***) : pushes the content of the address *ram* into the operation stack. Halts the program execution in case of stack overflow. - **SSPOPR** *ram*(2 byte - opcode ***237***) : pops one value out of the stack into the content of the address *ram*. Halts the program execution in case of stack underflow. Zero flag affected. - **SSPUSHI** *ref*(2 byte - opcode ***238***) : pushes the value referenced in RAM location *ref* into the operation stack. Halts the program execution in case of stack overflow. - **SSPOPI** *ref* (2 byte - opcode ***239***) : pops one value out of the stack into the value referenced in RAM location *ref*. Halts the program execution in case of stack underflow. Zero flag affected. - **SSHEAD** (1 byte - opcode ***240***) : copies the head the stack into the accumulator. Halts the program execution in case of empty stack. Zero flag affected. - **SSDEPTH** (1 byte - opcode ***241***) : returns the length of the stack into the accumulator. Zero flag is set if the stack is empty. # Samples programs - D0 : TEST - D1 : TEST - D2 : K2000 - D3 : Primes - Hardware DIV - D4 : Complement A2 - D5 : logicTrainer - D6 : operationTrainer - D7 : MASTERMIND # The DigiQt project All these new instructions are implemented in the DigiQt project : https://github.com/wawachief/DigiQt. This easy to use GUI allows you to - edit new program with a color syntax highlighting - assemble your program with an easy yet powerful syntax - debug your programs (single step, view RAM and registers, breakpoints) - simulate the Digirule with a realistc GUI # Get the firmware You can get the binary hex file Here : https://drive.google.com/drive/folders/1dwLxvtCJGBuTdACno-ls_LYQgG-knT0l?usp=sharing You need a PIC programmer (like the pickit3) and the software from Microchip to program the microcontroller.