{ "cells": [ { "cell_type": "markdown", "id": "1c7a11d9", "metadata": {}, "source": [ "This test will test (lol) the calling convention in Spider.\n", "As defined, it will use the CPU as a python object.\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "b9c572cd", "metadata": {}, "outputs": [], "source": [ "# The state of the \"my-language-name\" vm in a simple\n", "# python object abstraction\n", "my_language_name_vm = {\n", " 'regs':{\n", " 'RA':0,\n", " 'RB':0,\n", " 'RC':0,\n", " 'RD':0,\n", " 'RX':0,\n", " 'RY':0,\n", " 'R0':0,\n", " 'R1':0,\n", " 'R2':0,\n", " 'R3':0,\n", " 'R4':0,\n", " 'R5':0,\n", " 'R6':0,\n", " 'R7':0,\n", " 'R8':0,\n", " 'R9':0,\n", " 'RF':0,\n", " 'RI':0,\n", " 'RS':0,\n", " 'RZ':0,\n", " 'RE':0,\n", " 'RH':0,\n", " 'RV':0,\n", " 'RM':0,\n", " },\n", " 'stack': [],\n", "}" ] }, { "cell_type": "markdown", "id": "3e3989dc", "metadata": {}, "source": [ "**Test Data Definition**\n", "\n", "This block defines the parameters we want to pass into our hypothetical function and what we expect it to return. We use a mix of large data structures (sizes in bytes) and booleans (size 1) to force the VM to use all of its memory allocation rules." ] }, { "cell_type": "code", "execution_count": 3, "id": "a1ddd324", "metadata": {}, "outputs": [], "source": [ "# Input parameters, measured in bytes (booleans are size 1 for logic triggers)\n", "input_params = [\n", " {'name': 'int_a', 'size': 4}, # Should go to RA\n", " {'name': 'bool_1', 'size': 1}, # Should be queued\n", " {'name': 'bool_2', 'size': 1}, # Should be queued\n", " {'name': 'double_b', 'size': 8}, # Should go to RB\n", " {'name': 'big_struct', 'size': 32} # Too large for registers, forces stack usage\n", "]\n", "\n", "# Define the return types here\n", "output_return = [ \n", " {'name': 'ret1', 'size': 8} \n", "]" ] }, { "cell_type": "markdown", "id": "bbe2c356", "metadata": {}, "source": [ "Now, on this function it will perform the tasks of ordering the registers and stack based on the parameters.\n", "\n", "**The Function Call ABI**\n", "This is the core logic. It prepares the VM for a jump to another function by safely backing up the current context and routing the parameters to either the registers or the stack according to the strict hardware rules.\n", "\n", "**Step 1**: It pushes the caller-saved registers (R0-R3) to the stack so they aren't lost.\n", "\n", "**Step 2**: It checks if the function will return a massive object (> 16 bytes). If so, it reserves a pointer space.\n", "\n", "**Step 3**: It attempts to put parameters into RA, RB, RC, RD, R8, R9. Booleans are packed together to save space.\n", "\n", "**Step 4**: Anything that overflows the registers is pushed to the stack." ] }, { "cell_type": "code", "execution_count": null, "id": "02a2ad1a", "metadata": {}, "outputs": [], "source": [ "def do_function_call(input_params: list, output_return: list):\n", " global my_language_name_vm\n", " \n", " print(\"--- 1. Saving Caller State ---\")\n", " # Paso 1: Respaldar registros salvados por el llamador (R0-R3) \n", " caller_saved = ['R0', 'R1', 'R2', 'R3']\n", " for reg in caller_saved:\n", " my_language_name_vm['stack'].append(my_language_name_vm['regs'][reg])\n", " \n", " print(\"--- 2. Allocating Parameters ---\")\n", " \n", " # Regla: Si el retorno > 16 bytes, se agrega un puntero al INICIO de los parámetros \n", " actual_params = input_params.copy()\n", " ret_size = sum(r['size'] for r in output_return)\n", " if ret_size > 16:\n", " # Se inserta al frente para que ocupe RA (o el primer espacio disponible) \n", " actual_params.insert(0, {'name': 'RET_PTR_ALLOCATION', 'size': 8}) \n", "\n", " param_regs = ['RA', 'RB', 'RC', 'RD', 'R8', 'R9'] # \n", " reg_idx = 0\n", " bool_queue = []\n", " stack_params = []\n", " \n", " # --- FASE 1: ASIGNACIÓN A REGISTROS ---\n", " for param in actual_params:\n", " if reg_idx < len(param_regs):\n", " if param['size'] == 1: # Es Booleano \n", " bool_queue.append(param['name'])\n", " if len(bool_queue) == 8: # Cola llena (8 bytes/bits según lógica de la VM) \n", " my_language_name_vm['regs'][param_regs[reg_idx]] = f\"Packed_Bools({','.join(bool_queue)})\"\n", " reg_idx += 1\n", " bool_queue = []\n", " elif param['size'] <= 8: # Parámetro estándar\n", " # Antes de asignar un no-booleano, si hay booleanos pendientes, se deben flashear \n", " if bool_queue:\n", " my_language_name_vm['regs'][param_regs[reg_idx]] = f\"Padded_Bools({len(bool_queue)})\"\n", " reg_idx += 1\n", " bool_queue = []\n", " \n", " if reg_idx < len(param_regs):\n", " my_language_name_vm['regs'][param_regs[reg_idx]] = param['name']\n", " reg_idx += 1\n", " else:\n", " stack_params.append(param)\n", " else:\n", " # Si es muy grande para un registro (>8), va a la pila después \n", " stack_params.append(param)\n", " else:\n", " stack_params.append(param)\n", "\n", " # Flashear booleanos restantes si queda espacio en registros \n", " if bool_queue and reg_idx < len(param_regs):\n", " my_language_name_vm['regs'][param_regs[reg_idx]] = f\"Padded_Bools({len(bool_queue)})\"\n", " reg_idx += 1\n", " bool_queue = []\n", " elif bool_queue:\n", " # Si no hubo registros, los booleanos pendientes pasan a la lógica de pila\n", " stack_params = [{'name': b, 'size': 1} for b in bool_queue] + stack_params\n", " bool_queue = []\n", "\n", " # Regla VI: Si sobran registros, guardar SP y respaldar en stack \n", " while reg_idx < len(param_regs):\n", " my_language_name_vm['regs'][param_regs[reg_idx]] = \"SP_Backup\"\n", " my_language_name_vm['stack'].append(f\"SP_for_{param_regs[reg_idx]}\")\n", " reg_idx += 1\n", "\n", " # --- FASE 2: ASIGNACIÓN A PILA ---\n", " # 1. Parámetros <= 8 bytes (no booleanos)\n", " remaining_large = []\n", " for param in stack_params:\n", " if param['size'] == 1:\n", " bool_queue.append(param['name'])\n", " if len(bool_queue) == 8: # Formó un \"byte\" (o bloque) \n", " my_language_name_vm['stack'].append(\"Packed_Bools_Stack\")\n", " bool_queue = []\n", " elif param['size'] <= 8:\n", " my_language_name_vm['stack'].append(param['name'])\n", " else:\n", " remaining_large.append(param)\n", " \n", " # Flashear booleanos de la pila con padding \n", " if bool_queue:\n", " my_language_name_vm['stack'].append(\"Padded_Bools_Stack\")\n", " \n", " # 2. Finalmente parámetros grandes en orden \n", " for param in remaining_large:\n", " my_language_name_vm['stack'].append(f\"LARGE_{param['name']}\")" ] }, { "cell_type": "markdown", "id": "ac6440ca", "metadata": {}, "source": [ "Now, unwind the stack and stuff to make sure the machine goes back to its previous state BEFORE the function\n", "\n", "**The Function Cleanup ABI**\n", "Once the target function finishes executing and returns its answer in the registers, the caller function must clean up the mess it made on the stack before continuing.\n", "\n", "**Step 1**: It pops all the parameters that were pushed to the stack.\n", "\n", "**Step 2**: It pops the backup copies of R0-R3 and puts them back into the actual registers, restoring the caller's state perfectly." ] }, { "cell_type": "code", "execution_count": 5, "id": "d2e4ce44", "metadata": {}, "outputs": [], "source": [ "# TODO \n", "def undo_function_call(input_params: list, output_return: list):\n", " global my_language_name_vm\n", " \n", " print(\"--- 3. Cleaning Up Stack ---\")\n", " \n", " # 1. Calcular EXACTAMENTE cuántos elementos se pusieron en la pila (simulando la asignación)\n", " pops_needed = 0\n", " \n", " ret_size = sum(r['size'] for r in output_return)\n", " if ret_size > 16:\n", " pops_needed += 1\n", " \n", " param_regs = ['RA', 'RB', 'RC', 'RD', 'R8', 'R9']\n", " reg_idx = 0\n", " bool_queue = []\n", " stack_params = []\n", " \n", " # Simular qué se fue a registros y qué se fue a la pila\n", " for param in input_params:\n", " if reg_idx < len(param_regs):\n", " if param['size'] == 1:\n", " bool_queue.append(param['name'])\n", " if len(bool_queue) == 8:\n", " reg_idx += 1\n", " bool_queue = []\n", " elif param['size'] <= 8:\n", " reg_idx += 1\n", " elif param['size'] <= 16 and (len(param_regs) - reg_idx) >= 2:\n", " reg_idx += 2\n", " else:\n", " stack_params.append(param)\n", " else:\n", " stack_params.append(param)\n", " \n", " if len(bool_queue) > 0 and reg_idx < len(param_regs):\n", " reg_idx += 1\n", " bool_queue = []\n", " \n", " # Contar los respaldos del Stack Pointer (SP)\n", " while reg_idx < len(param_regs):\n", " pops_needed += 1 \n", " reg_idx += 1\n", " \n", " # Contar los argumentos reales que cayeron en la pila\n", " for param in stack_params:\n", " if param['size'] == 1:\n", " bool_queue.append(param['name'])\n", " if len(bool_queue) == 8:\n", " pops_needed += 1\n", " bool_queue = []\n", " else:\n", " pops_needed += 1 # Tanto <=8 como >8 ocupan 1 espacio en nuestra lista de Python\n", " \n", " if len(bool_queue) > 0:\n", " pops_needed += 1\n", "\n", " # 2. Hacer pop EXACTAMENTE de la cantidad calculada\n", " for _ in range(pops_needed):\n", " if my_language_name_vm['stack']:\n", " removed = my_language_name_vm['stack'].pop()\n", " print(f\"Popped parameter: {removed}\")\n", " \n", " # 3. Restaurar los Caller-Saved registers (siempre son 4)\n", " print(\"--- 4. Restoring Caller Registers ---\")\n", " caller_saved_order = ['R3', 'R2', 'R1', 'R0']\n", " for reg in caller_saved_order:\n", " if my_language_name_vm['stack']:\n", " restored_val = my_language_name_vm['stack'].pop()\n", " my_language_name_vm['regs'][reg] = restored_val\n", " print(f\"Restored {reg} <- {restored_val}\")" ] }, { "cell_type": "markdown", "id": "5397697f", "metadata": {}, "source": [ "VERY GOOD\n", "Now check the state of the machine before and after\n", "\n", "Try different combinations: One function call, multiple function calls, recursive calls, etc." ] }, { "cell_type": "code", "execution_count": 6, "id": "b58fbf72", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "--- 1. Saving Caller State ---\n", "--- 2. Allocating Parameters ---\n", "\n", "[STATE AFTER CALL]\n", "Registers: {'RA': 'int_a', 'RB': 'Padded_Bools(2)', 'RC': 'double_b', 'RD': 'SP_Backup', 'R8': 'SP_Backup', 'R9': 'SP_Backup'}\n", "Stack: [0, 0, 0, 0, 'SP_for_RD', 'SP_for_R8', 'SP_for_R9', 'LARGE_big_struct']\n", "\n", "========================================\n", "\n", "--- 3. Cleaning Up Stack ---\n", "Popped parameter: LARGE_big_struct\n", "Popped parameter: SP_for_R9\n", "Popped parameter: SP_for_R8\n", "Popped parameter: SP_for_RD\n", "--- 4. Restoring Caller Registers ---\n", "Restored R3 <- 0\n", "Restored R2 <- 0\n", "Restored R1 <- 0\n", "Restored R0 <- 0\n", "\n", "[STATE AFTER RETURN]\n", "Registers: {'RA': 'int_a', 'RB': 'Padded_Bools(2)', 'RC': 'double_b', 'RD': 'SP_Backup', 'R8': 'SP_Backup', 'R9': 'SP_Backup'}\n", "Stack: []\n" ] } ], "source": [ "# Execute the call simulation\n", "do_function_call(input_params, output_return)\n", "\n", "print(\"\\n[STATE AFTER CALL]\")\n", "print(\"Registers:\", {k: v for k, v in my_language_name_vm['regs'].items() if v != 0})\n", "print(\"Stack:\", my_language_name_vm['stack'])\n", "print(\"\\n\" + \"=\"*40 + \"\\n\")\n", "\n", "# Execute the cleanup simulation\n", "undo_function_call(input_params, output_return)\n", "\n", "print(\"\\n[STATE AFTER RETURN]\")\n", "print(\"Registers:\", {k: v for k, v in my_language_name_vm['regs'].items() if v != 0})\n", "print(\"Stack:\", my_language_name_vm['stack'])" ] }, { "cell_type": "markdown", "id": "4f700ac0", "metadata": {}, "source": [ "**Setup and Helper Function**\n", "First, let's create a quick helper to reset the VM so each test starts with a clean slate." ] }, { "cell_type": "code", "execution_count": 7, "id": "d225a397", "metadata": {}, "outputs": [], "source": [ "def reset_vm():\n", " global my_language_name_vm\n", " my_language_name_vm['stack'] = []\n", " for k in my_language_name_vm['regs']:\n", " my_language_name_vm['regs'][k] = 0\n", "\n", "# Standard parameters for testing\n", "test_params = [{'name': 'data', 'size': 8}]\n", "test_returns = [{'name': 'ret', 'size': 8}]" ] }, { "cell_type": "markdown", "id": "77df0216", "metadata": {}, "source": [ "**Test - Sequential Calls**\n", "This tests if the VM can call a function, clean up, and immediately call another function without the stack growing infinitely." ] }, { "cell_type": "code", "execution_count": 8, "id": "70347484", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "=== TEST 1: MULTIPLE SEQUENTIAL CALLS ===\n", "[Calling Function A]\n", "--- 1. Saving Caller State ---\n", "--- 2. Allocating Parameters ---\n", "--- 3. Cleaning Up Stack ---\n", "Popped parameter: SP_for_R9\n", "Popped parameter: SP_for_R8\n", "Popped parameter: SP_for_RD\n", "Popped parameter: SP_for_RC\n", "Popped parameter: SP_for_RB\n", "--- 4. Restoring Caller Registers ---\n", "Restored R3 <- 0\n", "Restored R2 <- 0\n", "Restored R1 <- 0\n", "Restored R0 <- 0\n", "\n", "[Calling Function B]\n", "--- 1. Saving Caller State ---\n", "--- 2. Allocating Parameters ---\n", "--- 3. Cleaning Up Stack ---\n", "Popped parameter: SP_for_R9\n", "Popped parameter: SP_for_R8\n", "Popped parameter: SP_for_RD\n", "Popped parameter: SP_for_RC\n", "Popped parameter: SP_for_RB\n", "--- 4. Restoring Caller Registers ---\n", "Restored R3 <- 0\n", "Restored R2 <- 0\n", "Restored R1 <- 0\n", "Restored R0 <- 0\n", "\n", "Final Stack (Should be empty): []\n" ] } ], "source": [ "print(\"=== TEST 1: MULTIPLE SEQUENTIAL CALLS ===\")\n", "reset_vm()\n", "\n", "print(\"[Calling Function A]\")\n", "do_function_call(test_params, test_returns)\n", "undo_function_call(test_params, test_returns)\n", "\n", "print(\"\\n[Calling Function B]\")\n", "do_function_call(test_params, test_returns)\n", "undo_function_call(test_params, test_returns)\n", "\n", "print(\"\\nFinal Stack (Should be empty):\", my_language_name_vm['stack'])" ] }, { "cell_type": "markdown", "id": "27f37c95", "metadata": {}, "source": [ "**Test - Recursive / Nested Calls**\n", "This is the most critical test. If Function A calls Function B, the VM must push a second frame onto the stack without destroying Function A's caller-saved registers (R0-R3)." ] }, { "cell_type": "code", "execution_count": 9, "id": "0c46e3f2", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "=== TEST 2: NESTED / RECURSIVE CALLS ===\n", "\n", "[1. Calling Outer Function]\n", "--- 1. Saving Caller State ---\n", "--- 2. Allocating Parameters ---\n", "Outer function modifies R0: IMPORTANT_OUTER_DATA\n", "\n", "[2. Calling Inner Function (Nested)]\n", "--- 1. Saving Caller State ---\n", "--- 2. Allocating Parameters ---\n", "Stack depth during nested call: 18\n", "\n", "[3. Returning from Inner Function]\n", "--- 3. Cleaning Up Stack ---\n", "Popped parameter: SP_for_R9\n", "Popped parameter: SP_for_R8\n", "Popped parameter: SP_for_RD\n", "Popped parameter: SP_for_RC\n", "Popped parameter: SP_for_RB\n", "--- 4. Restoring Caller Registers ---\n", "Restored R3 <- 0\n", "Restored R2 <- 0\n", "Restored R1 <- 0\n", "Restored R0 <- IMPORTANT_OUTER_DATA\n", "Did R0 survive the nested call?: IMPORTANT_OUTER_DATA\n", "\n", "[4. Returning from Outer Function]\n", "--- 3. Cleaning Up Stack ---\n", "Popped parameter: SP_for_R9\n", "Popped parameter: SP_for_R8\n", "Popped parameter: SP_for_RD\n", "Popped parameter: SP_for_RC\n", "Popped parameter: SP_for_RB\n", "--- 4. Restoring Caller Registers ---\n", "Restored R3 <- 0\n", "Restored R2 <- 0\n", "Restored R1 <- 0\n", "Restored R0 <- 0\n", "\n", "Final Stack (Should be empty): []\n" ] } ], "source": [ "print(\"=== TEST 2: NESTED / RECURSIVE CALLS ===\")\n", "reset_vm()\n", "\n", "# 1. We enter the Outer Function\n", "print(\"\\n[1. Calling Outer Function]\")\n", "do_function_call([{'name': 'outer_arg', 'size': 8}], test_returns)\n", "\n", "# Let's simulate the Outer Function doing some math and saving it in R0\n", "my_language_name_vm['regs']['R0'] = \"IMPORTANT_OUTER_DATA\"\n", "print(\"Outer function modifies R0:\", my_language_name_vm['regs']['R0'])\n", "\n", "# 2. Outer Function calls the Inner Function\n", "print(\"\\n[2. Calling Inner Function (Nested)]\")\n", "do_function_call([{'name': 'inner_arg', 'size': 8}], test_returns)\n", "\n", "print(\"Stack depth during nested call:\", len(my_language_name_vm['stack']))\n", "# Notice that \"IMPORTANT_OUTER_DATA\" is now safely backed up inside the stack!\n", "\n", "# 3. Inner Function returns\n", "print(\"\\n[3. Returning from Inner Function]\")\n", "undo_function_call([{'name': 'inner_arg', 'size': 8}], test_returns)\n", "\n", "# 4. Check if the Outer Function's data survived\n", "print(\"Did R0 survive the nested call?:\", my_language_name_vm['regs']['R0'])\n", "\n", "# 5. Outer Function returns\n", "print(\"\\n[4. Returning from Outer Function]\")\n", "undo_function_call([{'name': 'outer_arg', 'size': 8}], test_returns)\n", "\n", "print(\"\\nFinal Stack (Should be empty):\", my_language_name_vm['stack'])" ] }, { "cell_type": "markdown", "id": "2439376d", "metadata": {}, "source": [ "**1. External Interrupt**" ] }, { "cell_type": "code", "execution_count": 10, "id": "48b4d8f2", "metadata": {}, "outputs": [], "source": [ "def trigger_external_interrupt(interrupt_handler_address):\n", " global my_language_name_vm\n", " print(f\"\\n--- [EXTERNAL INTERRUPT] jumping to {hex(interrupt_handler_address)} ---\")\n", " \n", " # 1. Guardar el registro de banderas (RF) en el stack\n", " my_language_name_vm['stack'].append(my_language_name_vm['regs']['RF'])\n", " \n", " # 2. Guardar el valor actual de RV en el stack (para no perderlo)\n", " my_language_name_vm['stack'].append(my_language_name_vm['regs']['RV'])\n", " \n", " # 3. El manual dice que se genera un function call al valor de RV\n", " # Seteamos el destino en RV\n", " my_language_name_vm['regs']['RV'] = interrupt_handler_address\n", " \n", " # 4. Activar el bit de \"Interrupt Request\" en el registro de banderas\n", " # Asumiendo que es el Bit 2 (según convención estándar de este manual)\n", " my_language_name_vm['regs']['RF'] |= (1 << 2)\n", " \n", " # 5. Si existe un IFH (Interrupt Finish Handle), se prepara para después\n", " # (Por ahora simulamos que el PC/RI salta a la dirección de RV)\n", " my_language_name_vm['regs']['RI'] = interrupt_handler_address \n", " \n", " print(\"Estado guardado: RF y RV están en el stack. Bit de interrupción activo.\")" ] }, { "cell_type": "markdown", "id": "6ccdacec", "metadata": {}, "source": [ "**2. Internal Interrupt**" ] }, { "cell_type": "code", "execution_count": 11, "id": "6d3f0026", "metadata": {}, "outputs": [], "source": [ "def execute_internal_interrupt(interrupt_code):\n", " global my_language_name_vm\n", " \n", " # El manual especifica el código 0x0A para llamadas al Host\n", " if interrupt_code == 0x0A:\n", " print(\"\\n--- [INTERNAL INTERRUPT 0x0A] Calling Host Function ---\")\n", " \n", " # 1. Obtener el 'handle' de la función desde RV\n", " function_handle = my_language_name_vm['regs']['RV']\n", " \n", " # 2. Verificar si la función existe en la tabla del Host\n", " # (Simulamos una tabla de funciones simple)\n", " host_functions = {\n", " 1: lambda: \"Hello from Host!\",\n", " 2: lambda: 42\n", " }\n", " \n", " if function_handle in host_functions:\n", " # 3. Ejecutar y devolver resultado en registros de retorno (RA, RB, RC, RD)\n", " result = host_functions[function_handle]()\n", " print(f\"Executing handle {function_handle}: Result = {result}\")\n", " \n", " # Según la convención, el resultado va a RA\n", " my_language_name_vm['regs']['RA'] = result\n", " else:\n", " # 4. Si no existe, RV debe ser seteado a cero\n", " print(f\"Error: External function handle {function_handle} not found.\")\n", " my_language_name_vm['regs']['RV'] = 0\n", " else:\n", " print(f\"Unknown internal interrupt code: {hex(interrupt_code)}\")" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "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": 5 }