pkivolowitz/asm_book: a free ARM64 assembly textbook that starts from C

Who the ARM64 assembly book is written for

The README states the intended reader plainly: someone already comfortable with C or C++, and the book uses that assumed knowledge to bridge backward toward the instruction set architecture. That framing decides everything else. If you have never written C, the first chapters will not meet you where you are, because the explanations lean on constructs the reader is expected to recognize.

The second audience is the classroom. The README answers the question directly, saying the book can be used in courses covering assembly language. That matters because the repository is organized like a course: section_1, section_2 and section_3 sit at the top level alongside debugging, projects, python, reference_material and scripts. There is also a not_written_yet.md file, which tells you the book is a work in progress rather than a finished text.

The third audience is the reader who wants the corners of the ISA. The front matter says later chapters dive more deeply into the corners and recesses of the ARM V8 ISA and suit those who want to master the rich instruction set of 64 bit ARM processors. So the book has two slopes: a gentle one for people arriving from C, and a steeper one for people who intend to write a lot of assembly.

How the book bridges from C down to the ISA

The mechanism is pedagogical, not architectural. The README describes using C knowledge as a bridge backward toward the low level ISA, which means the reader meets assembly as the thing the compiler was already producing, not as an alien notation.

A second mechanism is the calling convention. The README explains that assembly depends closely on the underlying hardware and that the host operating environment plays an outsized role in how assembly programs are constructed, because a calling convention governs how functions are called and how parameters are passed. Originally the book taught only ARM Linux conventions. Over time the authors developed a suite of macros so the same code can be written for macOS or Linux, and the macros/ directory holds a current copy plus documentation.

The third mechanism is the deliberate choice to call into the C runtime instead of issuing OS system calls by hand. The README gives the example of calling write from assembly rather than making the system call directly. That wrapper handles the lower level details, and the benefit stated is portability: differences between distributions and architectures are masked by the CRT wrappers. There is a chapter under more/system_calls/ explaining what happens inside those wrappers. If you want to see raw syscall instructions, this book routes you around them first and explains them second.

Installing the toolchain and building your first .S file

There is nothing to install for the book itself. The README points at the toolchain instead. On Linux it gives these two commands, which install the compiler umbrella and the debugger:

sudo apt update
sudo apt install build-essential gdb

On macOS the README says to run the following in a terminal and follow the directions. Note its warning that gdb is replaced by lldb, with just enough differences to cause trouble:

xcode-select --install

The build step is the part that surprises people. The README uses gcc, the C compiler, to assemble assembly language, and explains the reason: the word compiler names only one stage of a sequence that also includes the preprocessor, the assembler and the linker. Because gcc is an umbrella, it drives all of them and links against the C runtime automatically.

A minimal self contained program whose main() is written in assembly is built like this. The README notes the result is written to a.out:

gcc main.S

Add the -g flag when you want a debugger to work properly, which the README states is often necessary:

gcc -g main.S

The file extension is load bearing. The README states that gcc invokes the C preprocessor when the file ends in a capital S, so #include and similar directives work, and that a lowercase s may or may not trigger it depending on your system. If you are mixing languages, the README shows the two accepted shapes, one all at once and one modular:

gcc main.c asm.S
gcc -c main.c
gcc -c asm.S
gcc main.o asm.o

The first form discards the intermediate object files. The second leaves the .o files on disk, which is what you want when only one module changed.

The capital S trap and other ways this book bites

The extension rule is the most common silent failure. Name a file main.s and the preprocessor never runs, so every #include disappears and the assembler reports symbols it has never seen. The README is explicit that this depends on the system, which is worse than a hard rule: the same file can behave differently on two machines.

Debugging is the second friction point. The README says gdb is replaced by lldb on the Mac with just enough differences to make you cry, and that without the -g flag your debugger may not properly operate. A reader following Linux instructions on Apple Silicon will need the macros/ suite and the more/apple_silicon/ chapter, not the plain Linux path.

The third limitation is scope. This is an ARM AArch64 book. Nothing in the README or the repository layout suggests x86 or RISC-V coverage, so if your target is an Intel server or an embedded part with a different ISA, the instruction chapters do not transfer. The calling convention discussion is tied to the platform as well, so the ABI details are ARM specific even where the programming advice is general.

Finally, the book is unfinished. The presence of not_written_yet.md and not_written_yet.pdf in the repository root, alongside section_1 through section_3, means some material is planned rather than written. A course adopting this needs to check the sections it depends on before assigning them. The README does not document an errata process or a way to report a wrong instruction, so corrections go through the repository like any other change.

How it compares with a compiler explorer workflow

The obvious alternative is not another book. It is the loop of writing C, compiling it with -S, and reading the assembly the compiler emits, often in a browser based compiler explorer. That approach has a real advantage: the assembly is always correct, always current, and tied to your exact compiler version and flags.

The difference in approach is direction. The compiler explorer loop starts from working C and shows you what came out, which teaches recognition. This book starts from the ISA and builds up, using C as the reference point, which teaches construction. If your goal is to read compiler output when a hot loop misbehaves, the explorer loop is faster and needs no toolchain installation. If your goal is to write a function in assembly, choose the calling convention deliberately, or understand why the compiler chose a particular register, you need the construction side, and that is what the sections under section_1, section_2 and section_3 provide.

The two are complementary in practice. The book's own build instructions use gcc, so you already have the compiler that produces the -S output. A reader can write the C, ask gcc for the assembly, then read the book's explanation of the registers and ABI that appear in it. What the book adds over the explorer is the macro suite for writing code that runs on both macOS and Linux, and the system_calls chapter explaining what the CRT wrapper does before the kernel is reached.

Maintenance, licensing and what a course would inherit

The repository is not archived, and the last push was on 2026-04-20. That is roughly five months before the date this article was written, which is recent enough that the project is not dormant, but the README gives no release history and no versioning scheme, so there is no changelog to read for breaking changes to the macros. A course adopting the book inherits whatever state section_1 through section_3 are in at the moment it clones.

The upgrade cost is mostly re-reading. Because the deliverable is prose plus a macro header set, an update can change the macros under a reader's existing code. Anyone building a course around the macros/ directory should pin to a specific commit rather than tracking main, since the README does not describe a stability policy for that directory.

On licensing, the repository carries LICENSE.md and LICENSE.pdf, and the metadata reports the licence as NOASSERTION, meaning no standard SPDX identifier was detected. That is a signal to read the actual licence file rather than assume a common open licence. Whether you can redistribute the text, print it for a class, or bundle the macros into your own repository depends on terms this article cannot summarize for you. Check LICENSE.md before you build anything on top of the macros, and treat the PDF alongside it as the authoritative rendering if the two differ.

Editorial conclusion

Adopt this book if you already write C or C++ and want the ARM V8 instruction set explained by bridging down from code you can read, or if you are teaching a course and need a table of contents to structure it. Do not adopt it if you want x86, if you want a library to link against, or if you expect a finished manuscript: not_written_yet.md exists in the repository root, and the README does not document a rollback or errata process. Before committing to it, check that section_1, section_2 and section_3 cover the ground you need, confirm the macros/ directory supports your target, and run the two apt or xcode-select commands above to see whether your toolchain produces a working a.out from a .S file.

Frequently asked questions

Official sources

1. Issues
2. pkivolowitz/asm_book on GitHub
3. README