Binder, the driver

A Binder call looks like a function call. Underneath it is one ioctl to a character device, a serialised buffer, and a kernel-side reference count. The gap between those two descriptions is where every Binder bug lives.

TL;DR#

• The client holds a proxy (BpBinder), the server holds a node (BBinder), and the driver translates between handles and nodes.
• A transaction is one ioctl carrying a target handle, a method code, flags and a Parcel. The driver copies the buffer into the receiver and wakes a thread from its pool.
• Objects sent over Binder are not copied. The driver creates a handle in the receiver and reference-counts the node; when the count reaches zero, the object dies and death notifications fire.
• The per-process transaction buffer is bounded, which is why large payloads throw TransactionTooLargeException instead of quietly working.
• oneway (glossary definition) calls skip the reply but still obey flow control: the driver blocks the sender when the receiver's async buffer is full.

Mental model#

Think of a company's internal courier system.

You do not send documents to a person; you send them to a desk number. The courier company keeps a directory that maps each desk number to a physical desk. When you hand over an envelope, the courier checks your employee badge, writes your name on the envelope, and carries it to the desk. The person at the desk signs a receipt, which comes back to you.

If the person at the desk has left the company, the courier returns the envelope marked recipient gone instead of leaving you waiting. And if you want to let the other desk send things back to you later, you do not give them your desk — you give them a claim ticket that the courier company can redeem on your behalf.

Where the analogy breaks#

The courier analogy implies a company that owns both offices. Binder's guarantee is stronger: the driver is not trusted by either side to be fair, only to be correct. And the "claim ticket" is more than an address — it keeps the original object alive. A Binder handle holds a reference count on the node, so the object cannot be destroyed while someone still holds a handle to it. That is reference counting, not directory lookup.

The big picture#

Switch the diagram between Synchronous and oneway and watch which steps disappear. The inbound half is identical; the difference is entirely in what happens after the server has the data. That is the right way to think about oneway: it is not a different transport, it is a different contract about the reply.

Deep dive#

The four objects#

Binder's programming model has a small vocabulary, and almost every confusion comes from mixing up two of these:

A BpBinder contains a handle, which is an integer meaningful only in that process. The driver keeps a per-process table mapping handle to node. Send the same IBinder to two processes and they get two different handles; the driver knows both refer to the same node.

This is why "pass a Binder object" is cheap. No state is copied — only a reference is created and a reference count is incremented.

The transaction, field by field#

A transaction is an ioctl on /dev/binder. The interesting fields are:

• handle — which node in the target process this is for.
• code — an integer method id. AIDL allocates these; hand-written Binder code picks its own.
• flags — TF_ONE_WAY is the important one. It tells the driver not to expect a reply.
• data — the Parcel buffer: interface descriptor, arguments, and any embedded file descriptors.
• reply — a second buffer the server writes its return value into.

The driver validates the handle, checks that the target process is alive, copies the buffer, and enqueues the transaction on the target's todo list. Then it wakes a thread. On the way back, the server calls BC_REPLY with the reply buffer, and the driver wakes the blocked client.

Parcels#

A Parcel (glossary definition) is a flat buffer with a write cursor and a read cursor. It knows how to serialise primitives, strings, arrays, IBinder references and file descriptors. Two details matter more than the rest.

File descriptors are duplicated, not copied. When you write a file descriptor into a Parcel, the driver installs an equivalent descriptor in the receiver. That is how Binder passes a shared-memory region or a socket without ever putting the data itself in the transaction.

The buffer is bounded. Each process has one transaction buffer, and a transaction that exceeds it fails. The exact size is a per-device configuration rather than a constant you should hardcode; what matters is that it is on the order of a megabyte and shared by all in-flight transactions in that process.¹ A large Bundle, a bitmap, or a long list sent in one call can exhaust it, which is what TransactionTooLargeException reports.

Reference counting and death#

The driver maintains a reference count per node. A handle in a client process counts as a reference; so does an entry in the driver's own tables. When the count drops to zero, the node is released.

Death notification is the other half. A client can register a DeathRecipient on an IBinder. When the process that owns the node dies, the driver fires a callback: the client's recipient is invoked with the dead binder, so it can clean up, retry, or report an error. This is why a well-written client can recover from a service crash without polling.

The mechanism is in the kernel, so it works for SIGKILL, for a native crash, and for a process that exits cleanly. It does not fire for a frozen process — freezing is not death, which is exactly the distinction the freezer machinery relies on.

oneway, flow control, and the async buffer#

A oneway method returns as soon as the driver has accepted the transaction. There is no reply, no return value, and no exception from the server — a oneway call cannot throw a remote exception because there is nowhere to put it.

The subtlety is that oneway calls from the same node are serialised. They may run on different threads, but never at the same time. If you send two oneway calls, the second cannot overtake the first. That is a useful guarantee and a common source of surprise for people who assume "async" means "unordered".²

The second subtlety is flow control. The receiver has a bounded buffer for asynchronous transactions. When it fills, oneway calls block in the driver until space frees up. A oneway call is therefore usually non-blocking, not always. The first oneway call to a busy target, or the thousandth in a burst, can block for a noticeable time.

The freezer#

Modern Android can freeze a cached app: the process stays in memory but gets no CPU. That changes what a Binder call to it means, and the driver is where the policy is enforced. The cached-app freezer was introduced in Android 10 and the policy was made more aggressive in Android 14.unverified(The AOSP freezer page describes the mechanism but does not state the release that introduced it, and this site's version data records only the Android 14 tightening.)

A synchronous call to a frozen process is not allowed to hang. The system kills the frozen process instead, on the theory that a caller should never block indefinitely on a target that cannot run. A oneway call is buffered until the target unfreezes; if the buffer overflows, the recipient can crash, and buffered calls may be stale by the time they are delivered.³

This is the clearest example of the general rule: Binder semantics are not just "call a function somewhere else". They encode the platform's policy about what happens when the other side is not available.

How it evolved#

Two rows deserve a note. The freezer changed the meaning of a call to a cached process, and Android 14 froze such apps more aggressively. Later releases also kept tightening what a Binder call may do to memory — the exact rules differ per release, so treat the direction as the stable part.

Under the hood#

• ‹›binder.c↗the transaction engine: ioctl handling, copy, thread wakeup
• ‹›binder_alloc.c↗the per-process buffer allocator — where the size limit lives
• ‹›BpBinder.cpp↗the client-side proxy
• ‹›IPCThreadState.cpp↗the server-side transaction loop
• ‹›Parcel.java↗the Java Parcel API

The allocator file is the one to read if you care about TransactionTooLargeException. The limit is not a check at the API boundary; it is the size of the buffer the allocator hands out.

Curiosity corner#

• A oneway call can still block. Flow control is the reason, and it is enforced by the driver, not the service.
• Handles are per-process. Printing a handle from one app tells you nothing about another app's handle for the same service.
• The driver is upstream. Binder lives in the mainline Linux tree, which is unusual for an Android-specific mechanism and the reason it survives kernel upgrades.

Try it#

$ adb shell dmesg | grep -i binder | head -20

$ adb shell ls -l /dev/binder*

Check yourself#

Sources#