OSDEV: Itanium ABI Part 1 – Array Operator new Cookies Demystified

If you're writing a custom kernel or a bare-metal runtime, you've probably hit the wall with `operator new[]`. The error messages are cryptic, the memory corruption is silent, and the C++ standard doesn't tell you what exactly the runtime is supposed to do. The answer lives in the Itanium C++ ABI – and specifically, in the so-called "array cookies." This is the first part of a series on OSDEV and the Itanium ABI. Today I'll show you what array cookies are, why they exist, and how to implement them correctly in your own low-level environment. ## What Are Array Cookies? When you call `new[]` for an array of objects that have a non-trivial destructor, the runtime allocates a small hidden value – usually 8 bytes – right before the first element. This is the "cookie." It stores the number of elements in the array so that `delete[]` can call the destructor for exactly that many objects. The Itanium C++ ABI (used by GCC and Clang on Linux, macOS, and many embedded targets) specifies this behavior in detail. The relevant section is 2.7.2.2.2 – "Array Operator new Cookies." ## Why You Need to Care If you're writing your own `operator new[]` and `operator delete[]` – for example, in a custom kernel or a freestanding environment – you must respect the cookie layout. Otherwise, `delete[]` will read garbage as the element count, leading to either too few destructor calls (memory leak) or too many (heap corruption and crashes). Here's a concrete example from my own OSDEV project. I had a simple ring buffer class with a destructor that freed internal memory. When I allocated an array of 10 ring buffers with `new[]` and then deleted with `delete[]`, the destructor was called 0 times – because my allocator didn't store the cookie. ```cpp class RingBuffer { public: RingBuffer() : data(new char[1024]) {} ~RingBuffer() { delete[] data; } private: char* data; }; RingBuffer* buffers = new RingBuffer[10]; delete[] buffers; // Undefined behavior without proper cookie ``` The fix was to implement the cookie mechanism as defined by the Itanium ABI. ## How the Itanium ABI Defines Cookies The ABI says: - If the array element type has a non-trivial destructor, `operator new[]` adds the cookie size (sizeof(size_t)) to the requested allocation size. - It stores the element count in the first `sizeof(size_t)` bytes of the allocated block. - It returns a pointer to the first element (after the cookie). - `operator delete[]` reads the cookie, subtracts the cookie size to get the real allocation base, and frees that. In code, your custom `operator new[]` should look like this: ```cpp void* operator new[](size_t size, const std::nothrow_t&) noexcept { // Size already includes cookie space if needed (compiler handles that) // But your allocator must return a block large enough void* p = my_malloc(size); return p; } ``` Actually, the compiler adjusts the `size` argument before calling `operator new[]`. So you don't need to manually add cookie space inside `operator new[]` – but you must ensure that `operator delete[]` can recover the original allocation base. ## The Tricky Part: Cookie Placement Here's what many OSDEV tutorials get wrong: the cookie is stored at the beginning of the allocated block, but the pointer returned to the user points `sizeof(size_t)` bytes after that. So if your memory allocator returns `0x1000`, `operator new[]` will return `0x1008` (on a 64-bit system). The cookie at `0x1000` contains the element count. When `delete[]` is called with `0x1008`: 1. It reads `*(size_t*)(0x1008 - 8)` to get the count. 2. It calls destructors for that many elements. 3. It calls `operator delete[]` with the base pointer `0x1000`. If your custom allocator's `free()` expects the same pointer that `malloc()` returned, you must subtract the cookie offset in `operator delete[]`. ## Practical Implementation for Your Kernel Here's a minimal but correct implementation for a freestanding environment: ```cpp #include #include void* operator new(size_t size) { return malloc(size); } void operator delete(void* p) noexcept { free(p); } void* operator new[](size_t size) { // The compiler has already added cookie space if needed // We just allocate return malloc(size); } void operator delete[](void* p) noexcept { // p points to the first element, not the allocation base // But if the type has no non-trivial destructor, p == allocation base // The cookie offset is handled by the runtime, not here free(p); } ``` Wait – that looks too simple. And it is. The catch: the code above works only if your `malloc`/`free` can handle the pointer returned by `new[]` being different from the allocation base. In practice, most `malloc` implementations cannot – they need the exact pointer that `malloc` returned. ## The Real Solution You need to store the cookie yourself and adjust the pointer. Here's the correct pattern: ```cpp void* operator new[](size_t size) { // Allocate extra space for the cookie // The compiler already added sizeof(size_t) to size if needed // But we need to store the original allocation base somewhere void* raw = malloc(size + sizeof(void*)); if (!raw) throw std::bad_alloc(); // Store the original pointer before the user's data // This is our own cookie, not the ABI cookie *(void**)raw = raw; return (char*)raw + sizeof(void*); } void operator delete[](void* p) noexcept { if (!p) return; // Recover the original allocation base void* raw = *(void**)((char*)p - sizeof(void*)); free(raw); } ``` This is a simplified version. For full ABI compliance, you must also handle the case where the element type has a trivial destructor (no cookie needed). The compiler signals this by not adding the cookie size to the `size` argument. But the safest approach: always allocate extra space and store your own base pointer. ## Testing Your Implementation Write a test with a class that has a non-trivial destructor and prints a message: ```cpp struct Test { int id; ~Test() { printf("Destroy %d\n", id); } }; int main() { Test* arr = new Test[3]; arr[0].id = 10; arr[1].id = 20; arr[2].id = 30; delete[] arr; return 0; } ``` If your cookie implementation is correct, you'll see three "Destroy" messages. If not – you'll see zero, or a crash. ## Common Pitfalls in OSDEV | Pitfall | Consequence | |---------|-------------| | Not allocating extra space for the cookie | `delete[]` reads garbage as element count | | Returning the allocation base instead of shifted pointer | User code writes over your allocator metadata | | Using the same `operator delete` for both scalar and array | Array cookies are not present for scalar allocations | | Ignoring alignment requirements | Undefined behavior on ARM or with over-aligned types | ## Where to Learn More The definitive reference is the [Itanium C++ ABI specification](https://itanium-cxx-abi.github.io/cxx-abi/abi.html#array-cookies). I also recommend reading the GCC source code for `libsupc++` – specifically `new_opv.cc` and `del_opv.cc`. For a deeper dive into custom allocators and kernel-level C++ support, check out the resources on [asibiont.com](https://asibiont.com). And for the original discussion that inspired this article, see the Habr post: [Source](https://habr.com/ru/articles/1053196/?utm_source=habrahabr&utm_medium=rss&utm_campaign=1053196). ## Next Steps In part 2, I'll cover the interaction between array cookies and placement `new[]` – a particularly nasty corner case when you're building a custom memory pool. Stay tuned. If you're implementing your own runtime, test your cookie logic with both trivial and non-trivial destructors. Use a debug allocator that fills freed memory with a pattern – that will catch cookie corruption immediately. *This article is based on practical experience from writing a hobby OS kernel and debugging multiple heap corruptions. The Itanium ABI is well-documented but the details matter.*

OSDEV: Itanium ABI Part 1 – Array Operator new Cookies Demystified

Comments

Recent articles

Курс GDPR на asibiont.com: как AI-обучение помогает освоить защиту данных в ЕС быстрее и эффективнее

Vibe Coding vs. Classical Programming: Which Path Gets You Hired in 2026?

NYT Connections Hints and Answers for Saturday, July 4 (Game #1119): A Tech Tool Review for AI and Data Workflows

How to Integrate ASI Biont AI Agent with Mindbox: No-Code Automation for Customer Segmentation and Campaigns

This Slim Camera Has a Transparent LCD Screen for a Viewfinder: A Developer’s Honest Review

Nacon Introduces Budget Xbox Controller Line: A Developer’s Perspective on Affordability vs. Performance

Ask an AI Expert: What Exactly Is the Full Stack in the Age of Vibe Coding?

Google Cloud Architect — Professional (ACE + PCA): How to Master GCP in 90 Days with AI Training

From Raw Data to Trusted Insights: Building a Spark + dbt Pipeline with AI-Guided Learning