← Back to all projects

LEARN C ABI DEEP DIVE

Learn C ABI: From Assembly to FFI Master

Goal: Deeply understand the Application Binary Interface (ABI)—the unspoken contract that governs how compiled code interacts. Move beyond source code and learn to think in terms of binary compatibility, calling conventions, and memory layout.

---

Why Learn the ABI?

Most C programmers write source code. Masters of C understand the binary code the compiler produces. The ABI is the set of rules—calling conventions, data alignment, name mangling—that allows different pieces of compiled code to work together. Knowing the ABI is the key to:

• Writing bug-free Foreign Function Interfaces (FFI) for Python, Rust, Go, etc.
• Designing stable libraries (.so/.dll) that can be updated without breaking user applications.
• Debugging low-level crashes related to stack corruption and memory alignment.
• Mastering assembly language by understanding the conventions that C compilers follow.
• Building high-performance, cross-platform code by understanding architecture-specific optimizations.

After completing these projects, you will see C code not just as text, but as a blueprint for a binary artifact with predictable, reliable behavior.

---

Core Concept Analysis

The C Application Binary Interface (ABI)

The ABI is a low-level, architecture-specific contract. It’s why code compiled with Clang on x86-64 Linux can link against and call code compiled with GCC. It defines the rules of the road for compiled machine code.

┌───────────────────────────────────────────────────┐
│                 Application Source Code           │
│   // main.c                                       │
│   #include "my_lib.h"                              │
│   int main() { my_func(10); return 0; }            │
└───────────────────────────────────────────────────┘
                 │
                 ▼ Compilation (obeys ABI rules)
┌───────────────────────────────────────────────────┐
│              Application Binary (main.o)          │
│   • Calls `my_func` according to convention       │
│   • Expects return value in a specific register   │
└───────────────────────────────────────────────────┘
                 │
                 ▼ Linking
┌───────────────────────────────────────────────────┐
│                Library Source Code                │
│   // my_lib.c                                     │
│   int my_func(int x) { return x * 2; }             │
└───────────────────────────────────────────────────┘
                 │
                 ▼ Compilation (obeys ABI rules)
┌───────────────────────────────────────────────────┐
│             Library Binary (my_lib.so)            │
│   • Symbol is named `my_func` (no name mangling)  │
│   • Reads argument from a specific register       │
│   • Puts return value in the correct register     │
└───────────────────────────────────────────────────┘

Key Pillars of the ABI

1. Calling Convention: The most important part. A set of rules for how functions call each other.
   • Argument Passing: Where do arguments go? In registers (e.g., RDI, RSI on x86-64) or on the stack?
   • Return Values: Where is the return value placed (e.g., RAX)?
   • Register Usage: Which registers must a function preserve (callee-saved) and which can it freely modify (caller-saved)?
   • Stack Management: Who is responsible for cleaning up the stack after a function call, the caller or the callee?
2. Data Layout and Alignment: How data types are arranged in memory.
   • Size: sizeof(int) might be different on different architectures.
   • Alignment: A uint64_t must often start on an 8-byte boundary. The ABI dictates this. Compilers insert padding bytes in structs to enforce it.
   • Struct Passing: How are structs passed as arguments? Are they passed on the stack, broken up into registers, or passed via a hidden pointer?
3. Symbol Naming (Name Mangling): The name a function has in the final binary.
   • C: Symbols are simple (e.g., my_func).
   • C++: Symbols are “mangled” to encode function signatures, namespaces, and classes to support overloading (e.g., _Z7my_funciv). This is why C and C++ are not ABI-compatible by default.

---

Project List

These projects will take you from observing the ABI in action to manually implementing and designing for it.

---

Project 1: The ABI Inspector

• File: LEARN_C_ABI_DEEP_DIVE.md
• Main Programming Language: C
• Alternative Programming Languages: Assembly (for reading)
• Coolness Level: Level 3: Genuinely Clever
• Business Potential: 1. The “Resume Gold”
• Difficulty: Level 2: Intermediate
• Knowledge Area: Assembly / Calling Conventions
• Software or Tool: GCC, Clang, GDB
• Main Book: “Computer Systems: A Programmer’s Perspective” by Bryant & O’Hallaron

What you’ll build: A collection of simple C functions and a corresponding “ABI report” where you document the generated assembly code, explaining how arguments are passed, how values are returned, and how the stack is managed.

Why it teaches the ABI: This is a project of pure observation. You will see exactly what your compiler does to obey the ABI. You’ll stop guessing about calling conventions and start knowing.

Core challenges you’ll face:

• Reading x86-64 assembly → maps to understanding mov, push, pop, call, ret
• Mapping C variables to registers → maps to tracking which argument goes into RDI, RSI, RDX, etc.
• Understanding the function prologue/epilogue → maps to push rbp; mov rbp, rsp and its purpose
• Analyzing struct passing → maps to seeing how the compiler breaks down structs into registers or passes them on the stack

Key Concepts:

• System V AMD64 ABI: The standard calling convention for Linux/macOS on x86-64. Search for the official PDF.
• x86-64 Assembly: “Computer Systems: A Programmer’s Perspective” Ch. 3 - Bryant & O’Hallaron
• Disassembly with GDB: Use the disassemble command in GDB.

Difficulty: Intermediate Time estimate: Weekend Prerequisites: C programming, comfort with the command line.

Real world outcome: You’ll have a C file and a markdown file. functions.c

// A function with many arguments
long func1(long a, long b, long c, long d, long e, long f, long g, long h) {
    return a + b + c + d + e + f + g + h;
}

// A function that takes a struct
struct Point { double x; double y; };
double func2(struct Point p) {
    return p.x + p.y;
}

report.md

# ABI Analysis for func1

- **Compiler**: GCC 11.2 on x86-64 Linux
- **Arguments `a` to `f`**: Passed in registers `rdi`, `rsi`, `rdx`, `rcx`, `r8`, `r9`.
- **Arguments `g` and `h`**: Pushed onto the stack. Found at `[rbp+16]` and `[rbp+24]`.
- **Return Value**: Returned in `rax`.

# ABI Analysis for func2

- **Struct `p`**: Passed in two floating-point registers, `xmm0` and `xmm1`, because it consists of two doubles.
...

Implementation Hints: Use gcc -S -O0 -fno-asynchronous-unwind-tables functions.c to generate human-readable assembly (-O0 is crucial). In the assembly file (functions.s), look for your function label. Trace the registers. For func1, you will see the compiler accessing [rbp+16] to get the 7th argument (g).

Learning milestones:

1. You can identify where the first 6 integer arguments are → You understand register-based argument passing.
2. You can identify where the 7th and 8th arguments are → You understand stack-based argument passing.
3. You can explain how a small struct is passed vs. a large one → You understand struct passing rules.
4. You can explain the purpose of rbp and rsp → You understand stack frame management.

---

Project 2: Struct Layout Detective

• File: LEARN_C_ABI_DEEP_DIVE.md
• Main Programming Language: C
• Alternative Programming Languages: C++, Rust
• Coolness Level: Level 3: Genuinely Clever
• Business Potential: 1. The “Resume Gold”
• Difficulty: Level 1: Beginner
• Knowledge Area: Memory Layout / Data Alignment
• Software or Tool: C compiler
• Main Book: “The C Programming Language” by Kernighan & Ritchie

What you’ll build: A C program that defines several structs with different member orders and uses sizeof and offsetof to print a detailed report of their memory layout, including the size and location of padding bytes.

Why it teaches the ABI: This project makes the abstract concept of “alignment” tangible. You’ll see wasted space appear and disappear based on how you order members, forcing you to understand the alignment rules of your platform’s ABI.

Core challenges you’ll face:

• Predicting sizeof → maps to understanding that sizeof(struct) is not just the sum of sizeof(member)
• Calculating padding → maps to manually applying alignment rules
• Observing architecture differences → maps to running the same code on x86 and ARM shows different results
• Forcing packed layout → maps to using __attribute__((packed)) and understanding the performance trade-offs

Key Concepts:

• Data Structure Alignment: Wikipedia has an excellent, detailed article on this.
• offsetof macro: stddef.h documentation.
• Type-safe printing: inttypes.h for macros like PRId64 to print architecture-independent types correctly.

Difficulty: Beginner Time estimate: Weekend Prerequisites: Basic C programming.

Real world outcome: A program that produces a report like this:

Analyzing 'struct Example1':
  sizeof = 16 bytes
  'c1' (char)  at offset 0, size 1
  -- padding -- at offset 1, size 7
  'd1' (double) at offset 8, size 8

Analyzing 'struct Example2' (optimized order):
  sizeof = 16 bytes
  'd1' (double) at offset 0, size 8
  'c1' (char)  at offset 8, size 1
  -- padding -- at offset 9, size 7 (or less if other members follow)

Conclusion: Reordering members to place larger types first can reduce padding.

Implementation Hints: Use the offsetof macro from <stddef.h>.

#include <stdio.h>
#include <stddef.h>

struct Example1 {
    char c1;
    double d1;
};

int main() {
    printf("Analyzing 'struct Example1':\n");
    printf("  sizeof = %zu bytes\n", sizeof(struct Example1));
    printf("  'c1' (char) at offset %zu\n", offsetof(struct Example1, c1));
    printf("  'd1' (double) at offset %zu\n", offsetof(struct Example1, d1));
    // Now, calculate and print the padding!
}

The rule of thumb for alignment is: a type of size N must have an address that is a multiple of N (up to a maximum, usually the word size). The total size of the struct will be padded to be a multiple of the alignment of its largest member.

Learning milestones:

1. You can correctly calculate padding between two members → You understand basic alignment rules.
2. You can correctly predict the total sizeof a struct → You understand end-of-struct padding.
3. You can reorder a struct’s members to minimize its size → You are applying your knowledge for optimization.
4. You can explain what __attribute__((packed)) does and why it can be slow → You understand the trade-off between space and CPU performance.

---

Project 3: The C vs. C++ Name Mangling Showdown

• File: LEARN_C_ABI_DEEP_DIVE.md
• Main Programming Language: C++
• Alternative Programming Languages: C
• Coolness Level: Level 2: Practical but Forgettable
• Business Potential: 1. The “Resume Gold”
• Difficulty: Level 1: Beginner
• Knowledge Area: Linking / Compilers
• Software or Tool: nm, objdump, or dumpbin (on Windows)
• Main Book: “A Tour of C++” by Bjarne Stroustrup

What you’ll build: A tiny C++ library with overloaded functions, functions in a namespace, and a class method. You will then compile it and use command-line tools to inspect the object file’s symbol table, documenting the “mangled” names. Finally, you’ll add extern "C" and see the difference.

Why it teaches the ABI: This project demystifies why you can’t just call C++ code from C. It shows that the symbol names in the binary—the “real” names used by the linker—are different, and extern "C" is the explicit instruction to use the simple C naming convention.

Core challenges you’ll face:

• Using linker tools → maps to learning to use nm or objdump -t
• Decoding mangled names → maps to recognizing patterns, or using c++filt to demangle them
• Understanding extern "C" → maps to seeing it as a directive that changes the “language linkage” of a function

Key Concepts:

• Name Mangling: Wikipedia provides a good overview.
• The nm command: man nm.
• extern "C": Any C++ book’s section on interoperability with C.

Difficulty: Beginner Time estimate: A few hours Prerequisites: Basic C++.

Real world outcome: You’ll have a C++ file and a report. lib.cpp:

namespace my_app {
    int do_work(int x) { return x; }
    int do_work(double y) { return (int)y; }
}

// This one will be C-compatible
extern "C" int callable_from_c(int a) {
    return a + 1;
}

nm_report.txt:

$ g++ -c lib.cpp
$ nm lib.o
... (mangled names) ...
000000000000001a T _Z6my_app7do_worki  <-- Mangled name for do_work(int)
0000000000000034 T _Z6my_app7do_workd  <-- Mangled name for do_work(double)
000000000000004e T callable_from_c      <-- Simple C name!
... (more output) ...

$ c++filt _Z6my_app7do_worki
my_app::do_work(int)

Implementation Hints: The nm command lists the symbols from object files. The second column is the symbol type (T means it’s in the text/code section). The third column is the symbol name. c++filt is a tool that demangles C++ symbols back into a human-readable form.

Learning milestones:

1. You can find the mangled names for your C++ functions → You have proof that C++ renames functions.
2. You can use c++filt to understand what the names mean → You can decode the mangling.
3. You can see the simple name for the extern "C" function → You understand how to create a C-compatible interface.
4. You can explain why C++ needs name mangling → You understand it’s to support features like overloading and namespaces.

---

Project 4: Cross-Language FFI Showdown

• File: LEARN_C_ABI_DEEP_DIVE.md
• Main Programming Language: C
• Alternative Programming Languages: Python, Rust, Go
• Coolness Level: Level 4: Hardcore Tech Flex
• Business Potential: 1. The “Resume Gold”
• Difficulty: Level 3: Advanced
• Knowledge Area: FFI / Interoperability
• Software or Tool: ctypes (Python), cgo (Go), Rust FFI
• Main Book: “The Rust Programming Language” (for its excellent FFI chapter)

What you’ll build: A simple C shared library (.so or .dll) that exports a few functions, including one that passes a struct. You will then write small programs in Python, Rust, and Go that load this library and call those functions.

Why it teaches the ABI: This project proves that the C ABI is the lingua franca of programming languages. You’ll learn that as long as your C library has a clean C interface (extern "C" if it were C++) and all languages agree on the data layout, everything just works. The struct passing will be the most enlightening part.

Core challenges you’ll face:

• Matching C types to foreign types → maps to ctypes.c_int in Python, i32 in Rust
• Replicating C struct layout → maps to creating a ctypes.Structure or a #[repr(C)] struct in Rust
• Handling pointers and memory → maps to understanding who allocates and who frees memory across the FFI boundary
• Configuring build systems for FFI → maps to linking the C library correctly in Go or Rust

Key Concepts:

• Foreign Function Interface (FFI): A mechanism by which a program written in one language can call routines from a library written in another.
• #[repr(C)]: Rust attribute to force a struct to have C-compatible memory layout.
• Python ctypes: Python’s standard library for calling C functions.

Difficulty: Advanced Time estimate: 1-2 weeks Prerequisites: Basics of Python, Rust, or Go. Project 3 is helpful.

Real world outcome: You’ll have a C library and client code in multiple languages that all work. libgeo.c:

struct Point { int x; int y; };
int get_x(struct Point p) { return p.x; }

main.py:

from ctypes import *

class Point(Structure):
    _fields_ = [("x", c_int), ("y", c_int)]

libgeo = CDLL("./libgeo.so")
libgeo.get_x.argtypes = [Point]
libgeo.get_x.restype = c_int

p = Point(x=10, y=20)
result = libgeo.get_x(p) # This call crosses the language boundary!
print(f"Result from C: {result}") # Prints 10

Implementation Hints: Start with a very simple C function like int add(int a, int b). Get that working in all three languages. Then, add the struct passing function. This is where you’ll have to carefully replicate the C struct layout in each language. Pay close attention to alignment and padding (Project 2 knowledge!).

Learning milestones:

1. You can call a simple C integer function from Python → You understand the basics of ctypes.
2. You can call the same function from Rust → You understand Rust’s FFI and build.rs.
3. You can successfully pass a struct from Go to C and get a correct result → You have mastered #[repr(C)]-style data layout replication.
4. You can write a function that takes a C string and explain why Python needs to encode it to bytes → You understand how different languages represent text.

---

Project 5: Crafting a Stable ABI with Opaque Pointers

• File: LEARN_C_ABI_DEEP_DIVE.md
• Main Programming Language: C
• Alternative Programming Languages: C++
• Coolness Level: Level 4: Hardcore Tech Flex
• Business Potential: 4. The “Open Core” Infrastructure
• Difficulty: Level 3: Advanced
• Knowledge Area: API Design / Library Development
• Software or Tool: Shared libraries (.so/.dll)
• Main Book: “C Interfaces and Implementations” by David R. Hanson

What you’ll build: A C shared library for a “counter” object. The key is that the public header file (counter.h) will not define the struct Counter—it will only forward-declare it. This makes the pointer “opaque”. You will then provide a V2 of your library with a completely different internal struct that is still 100% binary compatible with the original.

Why it teaches the ABI: This is the #1 technique for creating a stable ABI. By hiding implementation details behind an opaque pointer, you are free to change the implementation without forcing users to recompile their code. It minimizes the binary contract to a set of function signatures.

Core challenges you’ll face:

• Designing an opaque API → maps to only exposing pointers to incomplete types in headers
• Managing object lifecycle → maps to providing create, destroy, get, set functions
• Separating public header from internal implementation → maps to strict discipline in your code structure
• Proving binary compatibility → maps to swapping the .so file for a new version and having an old program still work

Key Concepts:

• Opaque Pointer (PIMPL Idiom): A widely used technique to hide private data members from a class or interface.
• API vs. ABI: The API is the source-level contract; the ABI is the binary-level contract. This project shows how to change the former slightly while preserving the latter.
• Dynamic Linking: How an executable finds and uses a .so file at runtime.

Difficulty: Advanced Time estimate: 1-2 weeks Prerequisites: C pointers, dynamic memory, experience building shared libraries.

Real world outcome: A library and a test program. V1 Library: counter.h (Public)

struct counter; // Incomplete type -> Opaque
typedef struct counter counter_t;

counter_t* counter_create(int initial_value);
void counter_destroy(counter_t* c);
void counter_increment(counter_t* c);
int counter_get_value(const counter_t* c);

counter_v1.c (Private)

#include "counter.h"
struct counter { int value; }; // Full definition is private!
// ... implementations of the functions ...

V2 Library: counter_v2.c (Private, new implementation)

#include "counter.h"
#include <string.h>
struct counter { char value_as_string[16]; }; // Totally different internal struct!
// ... new implementations that parse/format the string ...

You compile main.c against counter.h and libcounter_v1.so. Then, without recompiling main, you replace libcounter_v1.so with libcounter_v2.so, and the program still works.

Learning milestones:

1. You have a public header that never includes the full struct definition → You have created an opaque interface.
2. A client program can successfully use your V1 library → Your API design works.
3. You can completely refactor the internal struct in V2 → You are changing the implementation.
4. The original client program runs correctly with the V2 library without recompiling → You have achieved a stable ABI.

---

Summary

Project	Main Language	Difficulty	Focus
1. The ABI Inspector	C	Intermediate	Observing calling conventions in assembly
2. Struct Layout Detective	C	Beginner	Understanding memory alignment and padding
3. C vs. C++ Name Mangling	C++	Beginner	How linkers see symbols from different languages
4. Cross-Language FFI Showdown	C	Advanced	Using the C ABI as a universal language interface
5. Crafting a Stable ABI	C	Advanced	Designing libraries that don’t break on updates

```