Welcome! This repository provides a structured, curriculum-based approach to learning ARM64 (AArch64) assembly. It is designed to run on any native ARM64 hardware, including Linux servers, desktops, and Apple Silicon Macs.

This project contains two main learning tracks, as well as a sample folder for quickly testing your build environment.

• sample Folder: Use this first to ensure your toolchain is working correctly.
• baremetal Track: Learn pure assembly by interacting directly with the OS kernel.
• systems Track: Learn to integrate assembly with C++ for real-world applications.

Before starting the curriculum, use the sample folder to make sure everything is configured correctly.

make bare file=sample/baremetal-test/hello-bare.s
./bin/hello-bare

You should see "Hello Bare-Metal!" printed to your console.

make build file=sample/systems-test/hello-sys.s
./bin/hello-sys

You should see "Hello Systems!" printed to your console.

If both of these work, you are ready to start the curriculum!

The repository is organized like a course, with numbered folders that build upon each other. Start with 01_ in each track and work your way up.

HelloARM64/
├── sample/                # <-- Use this to test your setup
│   ├── baremetal-test/
│   └── systems-test/
├── baremetal/             # The bare-metal curriculum
│   ├── 01_Registers_and_Syscalls/
│   ├── 02_Memory_and_Data/
│   ├── 03_Arithmetic_and_Logic/
│   ├── 04_Control_Flow/
│   ├── 05_The_Stack_and_Functions/
│   ├── 06_Advanced_Memory_Addressing/
│   └── projects/
├── systems/               # The C++ interop curriculum
│   ├── 01_Basic_Interop/
│   ├── 02_Passing_Arguments/
│   ├── 03_Returning_Values/
│   ├── 04_Data_Structures/
│   ├── 05_Strings_and_Pointers/
│   ├── 06_Calling_Cpp_from_Asm/
│   └── projects/
├── tools/
└── Makefile

The Makefile and tools/ scripts are designed to work seamlessly with the new structure.

The bare command is for pure assembly files.

make bare file=baremetal/01_Registers_and_Syscalls/registers.s

The build command is for assembly files that have a corresponding main.cpp.

make build file=systems/01_Basic_Interop/hello.s

After building, you can run the output file from the bin/ directory:

./bin/registers
./bin/hello

• ARMv8-A Architecture Reference Manual
• Linux AArch64 syscall table
• Apple Developer Docs: macOS system calls
• Procedure Call Standard for the ARM 64-bit Architecture (AArch64)