NanoCore is a meticulously crafted emulator for a custom 8-bit CPU.

Designed with extreme minimalism in mind, this CPU operates within a strict 256-byte memory space, with all registers, the Program Counter (PC), and the Stack Pointer (SP) being 8-bit.

This project serves as an educational exercise in understanding the fundamental principles of computer architecture, low-level instruction set design, memory management under severe constraints, and assembly language programming.

• True 8-bit Architecture: All general-purpose registers (R0-R15), Program Counter (PC), and Stack Pointer (SP) are 8-bit.
• 256-byte Memory: The entire addressable memory space is limited to 256 bytes (0x00 to 0xFF), making it a challenge to write highly optimized and compact code.
• Variable-Length Instruction Set: Supports both 1-byte, 2-byte and 3-byte instructions to maximize opcode efficiency and flexibility within the limited address space.
• Modular Design: CPU cycle is broken down into distinct Fetch, Decode, and Execute phases for clarity.
• Inbuilt Two-Pass Assembler: The NanoCore Assembler makes it easier to program it by writing NanoCore Assembly instead of direct machine code.
• Terminal User Interface: Fully function TUI as seen above with breakpoints for easy debugging.

See programs/ for example programs and compiled binaries.

NanoCore features a small but functional instruction set designed for its 8-bit constraints.

• 1-byte instructions: One 8-bit opcode.
• 2-byte instructions: An 8-bit opcode followed by an 8-bit operand (e.g., an immediate value or an address).
• 3-byte instructions: An 8-bit opcode followed by two 8-bit operands (e.g., an immediate value or an address).

• val = Immediate value
• addr = Memory address
• Reg = Register
• Rs = Source register
• Rd = Destination register
• Z flag = Zero Flag
• R0 = 0x00, R1 = 0x01 ..., R15 = 0x0F
• All addition, subtraction, increment and decrement is wrapping.

To run the NanoCore emulator, you'll need to setup Rust locally.

1. Clone the repository:

   git clone https://github.com/AfaanBilal/nanocore.git
   cd nanocore

2. Run the example program: The programs/test.ncb file contains a small, assembled program that demonstrates the CPU's basic functionality.

   cargo run -- programs/test.ncb

   You should see the emulator's debug output and the program's output to your console. The source assembly file is programs/test.nca.

To assemble a program (say example.nca), run the NanoCore Assembler (nca):

cargo r --bin nca -- -i example.nca -o example.ncb

This should assemble the example.nca (NanoCore Assembly) to example.ncb (NanoCore Binary).

To run this assembled binary, run:

cargo r -- example.ncb

To assemble and run without saving a binary:

cargo r -- example.nca

Note that the filename MUST end with the .nca extension to be considered a NanoCore Assembly file which will be automatically assembled before running.

To run the TUI visualizer:

cargo r --bin tui -- programs/counter.nca

• CPU (cpu.rs): Defines the CPU's internal state, including registers, program counter, stack pointer, memory, and flag bits.
• NanoCore (nanocore.rs): The main emulator struct, responsible for loading programs, running cycles, and managing the CPU.
  • NanoCore::new(): Initializes a fresh computer state.
  • NanoCore::load_program(): Places machine code into the simulated memory.
  • NanoCore::run(): Executes the CPU cycle loop until halted.
  • NanoCore::cycle(): Performs a single CPU cycle (Fetch, Decode, Execute).
  • NanoCore::fetch_decode(): Reads the instruction byte(s) from memory and determines its type and operands.
  • NanoCore::execute_instruction(): Performs the operation defined by the decoded instruction, updating the CPU state.
• Assembler (assembler.rs): The NanoCore assembler core.
• Assembler bin (bin/nca.rs): The NanoCore assembler binary.
• TUI bin (bin/tui.rs): The NanoCore Terminal UI.

; Print the fibonacci sequence (two-digit)
start:
    LDI R0 0
    LDI R1 1
    LDI R2 12
    LDI R12 32
loop:
    JMP print_digits

post_print:
    MOV R3 R1
    ADD R1 R0
    MOV R0 R3
    DEC R2

    JNZ loop
end:
    HLT

print_digits:
    PUSH R10
    PUSH R11

    MOV R10 R0
    DIVI R10 10

    JZ unit_digit

    ADDI R10 48
    PRINT R10

unit_digit:
    MOV R11 R0
    MODI R11 10
    ADDI R11 48
    PRINT R11

print_space:
    PRINT R12

    POP R11
    POP R10
    JMP post_print

All contributions are welcome. Please create an issue first for any feature request or bug. Then fork the repository, create a branch and make any changes to fix the bug or add the feature and create a pull request. That's it! Thanks!

NanoCore is released under the MIT License. Check out the full license here.