bytecorebyte.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to ByteCore Byte\n",
    "\n",
    "Welcome to the ByteCore Byte notebook! This is a specialized version of the ByteCore CPU that operates within the ByteCore Emulator. Designed uniquely using the ByteCore Assembly language, it features a simplified addressing system that uses only 1 byte instead of 2. This change reduces the available memory from 64KB to just 256 bytes, providing a compact environment for exploring the capabilities of ByteCore.\n",
    "\n",
    "## What's in this Notebook?\n",
    "\n",
    "This notebook is structured to facilitate an interactive exploration of ByteCore Byte:\n",
    "- **Main ByteCore Byte Source Code:** The first Python cell contains the entire source code necessary for setting up ByteCore Byte.\n",
    "- **Example Programs:** Followed by two additional code cells that include:\n",
    "  - **Simple Example Program:** A straightforward program designed to demonstrate basic operations.\n",
    "  - **Advanced Example Program:** A more complex program that showcases advanced features.\n",
    "\n",
    "## Running the Examples\n",
    "\n",
    "To run the examples included in this notebook:\n",
    "1. Ensure you've followed the setup instructions to properly configure your environment.\n",
    "2. Open the `bytecorebyte.ipynb` notebook in Jupyter Lab.\n",
    "3. Click 'Run All' from the Jupyter Lab interface to execute the cells sequentially.\n",
    "\n",
    "Each program execution is followed by Python assertions that check and verify the CPU's state upon halting, ensuring that each step behaves as expected.\n",
    "\n",
    "Enjoy exploring ByteCore Byte and seeing assembly language principles in action within a controlled CPU simulation!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Main ByteCore Byte Source Code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bytecorecompiler.compiler import Compiler\n",
    "from bytecore.emulator import ByteCore\n",
    "\n",
    "bytecorebyte_bytecore_assembly = \"\"\"\n",
    ";--------------------\n",
    "; # ByteCore Byte\n",
    ";--------------------\n",
    "; Jump to start of program loop\n",
    "00 00 JMP\n",
    "00 01 02\n",
    "00 02 10\n",
    "\n",
    ";--------------------\n",
    "; ## Variables and OPCODES\n",
    ";--------------------\n",
    "01 00 00    ; Value  0 ; HALT\n",
    "01 01 01    ; Value  1 ; LOAD\n",
    "01 02 02    ; Value  2 ; STORE\n",
    "01 04 04    ; Value  4 ; ADD\n",
    "01 08 08    ; Value  8 ; SUB\n",
    "01 10 10    ; Value 16 ; JMP\n",
    "01 20 20    ; Value 32 ; JZ\n",
    "\n",
    ";--------------------\n",
    "; ## Program loop\n",
    ";--------------------\n",
    "; State\n",
    "02 00 00    ; Accumulator\n",
    "02 01 00    ; Opcode\n",
    "02 02 00    ; Data\n",
    "\n",
    ";--------------------\n",
    "; ### Start of program loop\n",
    ";--------------------\n",
    "; Get PC pointer\n",
    "02 10 LOAD\n",
    "02 11 21\n",
    "02 12 00\n",
    "02 13 STORE ; Store pointer to PC pointer\n",
    "02 14 02\n",
    "02 15 18\n",
    "\n",
    ";--------------------\n",
    "; ### Get PC value and store it in state\n",
    ";--------------------\n",
    "; Get PC value from pointer\n",
    "02 16 LOAD\n",
    "02 17 FF    ; FIXED\n",
    "02 18 FF\n",
    "02 19 STORE\n",
    "02 1A 02\n",
    "02 1B 01\n",
    "\n",
    ";--------------------\n",
    "; ### Check if OPCODE is HALT 00\n",
    ";--------------------\n",
    "02 1C JZ\n",
    "02 1D 02\n",
    "02 1E 22\n",
    "02 1F JMP   ; Was not HALT, jump to increment PC\n",
    "02 20 02\n",
    "02 21 50\n",
    "\n",
    "; Execute HALT\n",
    "02 22 LOAD  ; Get PC pointer\n",
    "02 23 21\n",
    "02 24 00\n",
    "02 25 STORE ; Store pointer to PC pointer\n",
    "02 26 02\n",
    "02 27 2D\n",
    "02 28 LOAD  ; Load accumulator\n",
    "02 29 02\n",
    "02 2A 00\n",
    "02 2B JMP   ; HALT at PC\n",
    "02 2C FF    ; FIXED\n",
    "02 2D FF\n",
    "\n",
    ";--------------------\n",
    "; ### Increment PC\n",
    ";--------------------\n",
    "; Return address variables\n",
    "02 40 02\n",
    "02 41 5F\n",
    "\n",
    "; Copy return address to PC\n",
    "02 50 LOAD\n",
    "02 51 02\n",
    "02 52 40\n",
    "02 53 STORE\n",
    "02 54 21\n",
    "02 55 03\n",
    "02 56 LOAD\n",
    "02 57 02\n",
    "02 58 41\n",
    "02 59 STORE\n",
    "02 5A 21\n",
    "02 5B 04\n",
    "\n",
    "; Call subroutine: ++PC\n",
    "02 5C JMP\n",
    "02 5D 21\n",
    "02 5E 05\n",
    "\n",
    ";--------------------\n",
    "; ### Get DATA value and store it in state\n",
    ";--------------------\n",
    "; Get PC value from pointer\n",
    "02 5F LOAD\n",
    "02 60 21\n",
    "02 61 00\n",
    "02 62 STORE\n",
    "02 63 02\n",
    "02 64 67\n",
    "\n",
    "; Get PC value from pointer\n",
    "02 65 LOAD\n",
    "02 66 FF    ; FIXED\n",
    "02 67 FF\n",
    "02 68 STORE\n",
    "02 69 02\n",
    "02 6A 02\n",
    "02 6B JMP\n",
    "02 6C 02\n",
    "02 6D 70\n",
    "\n",
    ";--------------------\n",
    "; ### Check if OPCODE is LOAD 01\n",
    ";--------------------\n",
    "02 70 LOAD\n",
    "02 71 02\n",
    "02 72 01\n",
    "02 73 SUB   ; Accumulator - 1\n",
    "02 74 01\n",
    "02 75 01\n",
    "02 76 JZ    ; Is opcode LOAD\n",
    "02 77 02\n",
    "02 78 7C\n",
    "02 79 JMP   ; Is not opcode LOAD, try next\n",
    "02 7A 02\n",
    "02 7B 90\n",
    "\n",
    "; Execute LOAD\n",
    "02 7C LOAD\n",
    "02 7D 02\n",
    "02 7E 02\n",
    "02 7F STORE\n",
    "02 80 02\n",
    "02 81 84\n",
    "02 82 LOAD  ; Resolve pointer\n",
    "02 83 FF    ; FIXED\n",
    "02 84 FF\n",
    "02 85 STORE ; Store to accumulator\n",
    "02 86 02\n",
    "02 87 00\n",
    "02 88 JMP   ; Jump to increment PC\n",
    "02 89 03\n",
    "02 8A 70\n",
    "\n",
    ";--------------------\n",
    "; ### Check if OPCODE is STORE 02\n",
    ";--------------------\n",
    "02 90 LOAD\n",
    "02 91 02\n",
    "02 92 01\n",
    "02 93 SUB   ; Accumulator - 2\n",
    "02 94 01\n",
    "02 95 02\n",
    "02 96 JZ    ; Is opcode STORE\n",
    "02 97 02\n",
    "02 98 9C\n",
    "02 99 JMP   ; Is not opcode STORE, try next\n",
    "02 9A 02\n",
    "02 9B B0\n",
    "\n",
    "; Execute STORE\n",
    "02 9C LOAD\n",
    "02 9D 02\n",
    "02 9E 02\n",
    "02 9F STORE\n",
    "02 A0 02\n",
    "02 A1 A7\n",
    "02 A2 LOAD  ; Load from accumulator\n",
    "02 A3 02\n",
    "02 A4 00\n",
    "02 A5 STORE ; Resolve pointer\n",
    "02 A6 FF    ; FIXED\n",
    "02 A7 FF\n",
    "02 A8 JMP   ; Jump to increment PC\n",
    "02 A9 03\n",
    "02 AA 70\n",
    "\n",
    ";--------------------\n",
    "; ### Check if OPCODE is ADD 04\n",
    ";--------------------\n",
    "02 B0 LOAD\n",
    "02 B1 02\n",
    "02 B2 01\n",
    "02 B3 SUB   ; Accumulator - 4\n",
    "02 B4 01\n",
    "02 B5 04\n",
    "02 B6 JZ    ; Is opcode ADD\n",
    "02 B7 02\n",
    "02 B8 BC\n",
    "02 B9 JMP   ; Is not opcode ADD, try next\n",
    "02 BA 02\n",
    "02 BB D0\n",
    "\n",
    "; Execute ADD\n",
    "02 BC LOAD  ; Load data pointer stored in state\n",
    "02 BD 02\n",
    "02 BE 02\n",
    "02 BF STORE ; Store data pointer\n",
    "02 C0 02\n",
    "02 C1 C7\n",
    "02 C2 LOAD  ; Load accumulator from state\n",
    "02 C3 02\n",
    "02 C4 00\n",
    "02 C5 ADD   ; Resolve pointer\n",
    "02 C6 FF    ; FIXED\n",
    "02 C7 FF\n",
    "02 C8 STORE ; Store back to accumulator stored in state\n",
    "02 C9 02\n",
    "02 CA 00\n",
    "02 CB JMP   ; Jump to increment PC\n",
    "02 CC 03\n",
    "02 CD 70\n",
    "\n",
    ";--------------------\n",
    "; ### Check if OPCODE is SUB 08\n",
    ";--------------------\n",
    "02 D0 LOAD\n",
    "02 D1 02\n",
    "02 D2 01\n",
    "02 D3 SUB   ; Accumulator - 8\n",
    "02 D4 01\n",
    "02 D5 08\n",
    "02 D6 JZ    ; Is opcode SUB\n",
    "02 D7 02\n",
    "02 D8 DC\n",
    "02 D9 JMP   ; Is not opcode SUB, try next\n",
    "02 DA 02\n",
    "02 DB F0\n",
    "\n",
    "; Execute SUB\n",
    "02 DC LOAD  ; Load data pointer stored in state\n",
    "02 DD 02\n",
    "02 DE 02\n",
    "02 DF STORE ; Store data pointer\n",
    "02 E0 02\n",
    "02 E1 E7\n",
    "02 E2 LOAD  ; Load accumulator from state\n",
    "02 E3 02\n",
    "02 E4 00\n",
    "02 E5 SUB   ; Resolve pointer\n",
    "02 E6 FF    ; FIXED\n",
    "02 E7 FF\n",
    "02 E8 STORE ; Store back to accumulator stored in state\n",
    "02 E9 02\n",
    "02 EA 00\n",
    "02 EB JMP   ; Jump to increment PC\n",
    "02 EC 03\n",
    "02 ED 70\n",
    "\n",
    ";--------------------\n",
    "; ### Check if OPCODE is JMP 10\n",
    ";--------------------\n",
    "02 F0 LOAD\n",
    "02 F1 02\n",
    "02 F2 01\n",
    "02 F3 SUB   ; Accumulator - 16\n",
    "02 F4 01\n",
    "02 F5 10\n",
    "02 F6 JZ    ; Is opcode JMP\n",
    "02 F7 02\n",
    "02 F8 FC\n",
    "02 F9 JMP   ; Is not opcode JMP, try next\n",
    "02 FA 03\n",
    "02 FB 10\n",
    "\n",
    "; Execute JMP\n",
    "02 FC LOAD  ; Load data pointer stored in state\n",
    "02 FD 02\n",
    "02 FE 02\n",
    "02 FF STORE ; Store to PC\n",
    "03 00 21\n",
    "03 01 00\n",
    "03 02 JMP   ; Jump to loop to top (do not increment PC)\n",
    "03 03 03\n",
    "03 04 80\n",
    "\n",
    ";--------------------\n",
    "; ### Check if OPCODE is JZ 20\n",
    ";--------------------\n",
    "03 10 LOAD\n",
    "03 11 02\n",
    "03 12 01\n",
    "03 13 SUB   ; Accumulator - 32\n",
    "03 14 01\n",
    "03 15 20\n",
    "03 16 JZ    ; Is opcode JZ\n",
    "03 17 03\n",
    "03 18 1C\n",
    "03 19 JMP   ; Is not opcode JZ, jump to invalid opcode\n",
    "03 1A 03\n",
    "03 1B 40\n",
    "\n",
    "; Execute JZ\n",
    "03 1C LOAD  ; Load data pointer stored in state\n",
    "03 1D 02\n",
    "03 1E 00\n",
    "03 1F JZ    ; Is zero, execute JMP\n",
    "03 20 02\n",
    "03 21 FC\n",
    "03 22 JMP   ; Is not zero, jump to increment PC\n",
    "03 23 03\n",
    "03 24 70\n",
    "\n",
    ";--------------------\n",
    "; ### Invalid Opcode\n",
    ";--------------------\n",
    "; Return address variables\n",
    "03 30 03\n",
    "03 31 4F\n",
    "\n",
    "; Copy return address to PC\n",
    "03 40 LOAD\n",
    "03 41 03\n",
    "03 42 30\n",
    "03 43 STORE\n",
    "03 44 21\n",
    "03 45 03\n",
    "03 46 LOAD\n",
    "03 47 03\n",
    "03 48 31\n",
    "03 49 STORE\n",
    "03 4A 21\n",
    "03 4B 04\n",
    "\n",
    "; Call subroutine: --PC\n",
    "03 4C JMP\n",
    "03 4D 21\n",
    "03 4E 08\n",
    "\n",
    "03 4F JMP   ; Jump to HALT\n",
    "03 50 02\n",
    "03 51 22\n",
    "\n",
    ";--------------------\n",
    "; ### Increment PC\n",
    ";--------------------\n",
    "; Return address variables\n",
    "03 60 03\n",
    "03 61 80\n",
    "\n",
    "; Copy return address to PC\n",
    "03 70 LOAD\n",
    "03 71 03\n",
    "03 72 60\n",
    "03 73 STORE\n",
    "03 74 21\n",
    "03 75 03\n",
    "03 76 LOAD\n",
    "03 77 03\n",
    "03 78 61\n",
    "03 79 STORE\n",
    "03 7A 21\n",
    "03 7B 04\n",
    "\n",
    "; Call subroutine: ++PC\n",
    "03 7C JMP\n",
    "03 7D 21\n",
    "03 7E 05\n",
    "\n",
    ";--------------------\n",
    "; ### Loop to top\n",
    ";--------------------\n",
    "03 80 JMP\n",
    "03 81 02\n",
    "03 82 10\n",
    "\n",
    ";--------------------\n",
    "; ## Subroutines\n",
    ";--------------------\n",
    "\n",
    ";--------------------\n",
    "; ### PC - Program Counter\n",
    ";--------------------\n",
    "21 00 00    ; PC variable\n",
    "21 01 01    ; Value  1\n",
    "; Return address\n",
    "21 02 JMP\n",
    "21 03 FE\n",
    "21 04 FF\n",
    "; Subroutine ++PC\n",
    "21 05 JMP\n",
    "21 06 21\n",
    "21 07 10\n",
    "; Subroutine --PC\n",
    "21 08 JMP\n",
    "21 09 21\n",
    "21 0A 20\n",
    "\n",
    ";--------------------\n",
    "; #### Subroutine ++PC\n",
    ";--------------------\n",
    "21 10 LOAD\n",
    "21 11 21\n",
    "21 12 00\n",
    "21 13 ADD\n",
    "21 14 21\n",
    "21 15 01\n",
    "21 16 STORE\n",
    "21 17 21\n",
    "21 18 00\n",
    "\n",
    "21 19 JMP\n",
    "21 1A 21\n",
    "21 1B 02\n",
    "\n",
    ";--------------------\n",
    "; #### Subroutine --PC\n",
    ";--------------------\n",
    "21 20 LOAD\n",
    "21 21 21\n",
    "21 22 00\n",
    "21 23 SUB\n",
    "21 24 21\n",
    "21 25 01\n",
    "21 26 STORE\n",
    "21 27 21\n",
    "21 28 00\n",
    "\n",
    "21 29 JMP\n",
    "21 2A 21\n",
    "21 2B 02\n",
    ";--------------------\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simple Example Program"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "simple_program_bytecore_assembly = \"\"\"\n",
    "FF 00 01 ; LOAD\n",
    "FF 01 0A\n",
    "FF 02 04 ; ADD\n",
    "FF 03 0B\n",
    "FF 04 02 ; STORE\n",
    "FF 05 FF\n",
    "FF 06 00 ; HALT\n",
    "FF 0A 14 ; 20\n",
    "FF 0B 1E ; 30\n",
    "\"\"\"\n",
    "\n",
    "# Arrange\n",
    "expected = 50\n",
    "bytecore_assembly = '\\n'.join(\n",
    "    [bytecorebyte_bytecore_assembly, simple_program_bytecore_assembly])\n",
    "\n",
    "# Act\n",
    "memory_bytes = Compiler(bytecore_assembly).get_memory_bytes()\n",
    "byte_core = ByteCore(memory_bytes)\n",
    "byte_core.cycle_until_halt()\n",
    "dump = byte_core.dump()\n",
    "\n",
    "# Assert\n",
    "pc_msb = dump.pc_msb_register.value\n",
    "pc_lsb = dump.pc_lsb_register.value\n",
    "pc = pc_msb * 256 + pc_lsb\n",
    "assert pc == int('FF_06', 16)\n",
    "\n",
    "accumulator = dump.accumulator.value\n",
    "assert accumulator == expected\n",
    "\n",
    "actual = dump.memory[int('FF_FF', 16)].value\n",
    "assert actual == expected"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Advanced Example Program"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "advanced_program_bytecore_assembly = \"\"\"\n",
    "FF 00 10 ; JMP\n",
    "FF 01 20\n",
    "\n",
    "FF 10 37 ; 55\n",
    "FF 11 14 ; 20\n",
    "FF 12 02 ;  2\n",
    "FF 13 01 ;  1\n",
    "\n",
    "FF 20 01 ; LOAD\n",
    "FF 21 10\n",
    "FF 22 04 ; ADD\n",
    "FF 23 12\n",
    "FF 24 02 ; STORE\n",
    "FF 25 10\n",
    "FF 26 01 ; LOAD\n",
    "FF 27 11\n",
    "FF 28 08 ; SUB\n",
    "FF 29 13\n",
    "FF 2A 02 ; STORE\n",
    "FF 2B 11\n",
    "FF 2C 01 ; LOAD\n",
    "FF 2D 11\n",
    "FF 2E 20 ; JZ\n",
    "FF 2F 80\n",
    "FF 30 10 ; JMP\n",
    "FF 31 20\n",
    "\n",
    "FF 80 01 ; LOAD\n",
    "FF 81 10\n",
    "FF 82 02 ; STORE\n",
    "FF 83 FF\n",
    "FF 84 00 ; HALT\n",
    "\"\"\"\n",
    "\n",
    "# Arrange\n",
    "expected = 95\n",
    "bytecore_assembly = '\\n'.join(\n",
    "    [bytecorebyte_bytecore_assembly, advanced_program_bytecore_assembly])\n",
    "\n",
    "# Act\n",
    "memory_bytes = Compiler(bytecore_assembly).get_memory_bytes()\n",
    "byte_core = ByteCore(memory_bytes)\n",
    "byte_core.cycle_until_halt()\n",
    "dump = byte_core.dump()\n",
    "\n",
    "# Assert\n",
    "pc_msb = dump.pc_msb_register.value\n",
    "pc_lsb = dump.pc_lsb_register.value\n",
    "pc = pc_msb * 256 + pc_lsb\n",
    "assert pc == int('FF_84', 16)\n",
    "\n",
    "accumulator = dump.accumulator.value\n",
    "assert accumulator == expected\n",
    "\n",
    "actual = dump.memory[int('FF_FF', 16)].value\n",
    "assert actual == expected"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## License\n",
    "\n",
    "This project is licensed under the terms of the MIT License. See the [LICENSE](https://github.com/joakimwinum/bytecore-byte/blob/main/LICENSE) file for the full text."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}