AIDL: the interface language

The Binder driver moves bytes. It has no idea what a Task is, which method you meant, or whether an argument is in or out. Every one of those decisions has to be made somewhere, and doing it by hand in both processes is how you get two implementations that disagree.

TL;DR#

• An .aidl file declares one interface in Java-like syntax. The build generates an interface, a Stub for the server and a Proxy for the client.
• Arguments must be marked in, out or inout unless they are primitives, String, IBinder or another AIDL interface, which default to in.
• oneway methods have no return value and no exceptions. Calls from the same node stay ordered but do not wait.
• Interfaces are versioned by appending: add methods at the end, never renumber, and assign explicit transaction codes when you need to.
• The same language has three backends — Java, NDK (C++) and Rust — which is why AIDL replaced HIDL for vendor interfaces.¹²

Mental model#

Think of a restaurant menu and its kitchen ticket system.

The menu is the .aidl file: a list of dishes with names and descriptions. It is the only thing the customer and the kitchen both agree on.

The ticket is a transaction: a numbered order with the table, the dish code and any special requests. The waiter does not shout the order across the room; the ticket travels on a rail.

The order pad is the generated Proxy: it turns "one margherita, no basil" into a ticket with the right code. The ticket rail and the chef's numbering are the driver.

Where the analogy breaks#

A menu is prose and a kitchen can improvise. AIDL is a binary contract: the method code, the argument order and the parcel format are fixed at build time, and both sides must be built from the same definition. Change the interface without changing both sides and you do not get a creative interpretation — you get an exception, or worse, silently misread fields.

The big picture#

Click the labelled steps under the diagram to trace one method from the .aidl declaration through the generated constants, the server's onTransact and the client's transact call. The generated code shown is illustrative of the documented Stub/asInterface and Proxy shape; exact output differs by AIDL version and backend.

Deep dive#

What the compiler generates#

For a single .aidl file you get a Java interface (or a Kotlin/NDK/Rust equivalent) with three layers:

1. The interface — extends android.os.IInterface, declares your methods plus asBinder(), and defines a TRANSACTION_* integer per method.
2. Stub — an abstract class extending Binder that implements the interface. Its onTransact reads the method code, decodes the Parcel, calls your implementation, and writes the result. It also provides asInterface(IBinder), which returns the local object when the binder is in the same process and a proxy otherwise.
3. Proxy — a private class holding the remote IBinder. Each method writes the descriptor and arguments, calls transact(), and reads the reply.

The same-process shortcut in asInterface is easy to miss and important: a bound service in your own process does not pay for Binder at all. queryLocalInterface returns the real implementation, and the call is an ordinary virtual call.

Writing the interface#

An .aidl file holds exactly one interface or parcelable. The parameter direction markers are the part people get wrong most often:

in means the value is marshalled from client to server. out means the server fills it and the client reads it back — which requires Binder to write the result into the reply. inout does both, and costs two copies of the data.

// ITaskService.aidl
package com.example.tasks;
 
import com.example.tasks.Task;
 
interface ITaskService {
  int getTaskCount();
 
  List<Task> getTasks();
 
  void addTask(in Task task) = 3;
 
  oneway void notifyChanged(int reason);
}

The = 3 is an explicit transaction code. By default AIDL numbers methods by their position in the file, which means inserting a method in the middle silently changes every later number. Assigning codes explicitly makes that change safe, at the cost of managing the numbers yourself.

oneway in AIDL#

Marking a method oneway has three consequences, and all three are enforced by the generated code and the driver rather than by convention:

• The method must return void. There is no reply to carry a value.
• It cannot throw a checked remote exception to the caller, because there is no return path.
• The proxy sets FLAG_ONEWAY, so the driver does not block the calling thread waiting for a reply.

What oneway does not give you is parallelism. Calls from one node to one target are serialised: the second cannot run until the first has been dispatched, even though they may be handled by different threads.³ If you need true concurrency, you need multiple targets or a different design.

Versioning#

AIDL has no explicit major versions. The rules are:

• Append methods to the end of an interface; never reorder or remove.
• Append fields to the end of a parcelable.
• Put an incompatible change in a new package name rather than breaking the old one.

That is in-place versioning, and it is what lets a vendor interface evolve while old clients keep working. For HALs there is an extra layer: interfaces that cross the system/vendor boundary must be frozen at a released version, and VTS checks that both sides agree on the exact frozen definition.²

Three backends, one language#

AIDL is not only a Java tool. The same .aidl file can generate:

• Java — for app and framework code, using libbinder through JNI.
• NDK (C++) — for native services, linking libbinder_ndk.
• Rust — for new native code, with a binder crate.

That portability is why AIDL replaced HIDL. HIDL was designed for the vendor interface and was C++-centric; AIDL already existed for app developers and could be extended to cover the same ground with a syntax people already knew. HIDL has been deprecated since Android 10.⁴

Errors, death and the things AIDL does not do#

AIDL gives you RemoteException and, for service-specific failures, a status code or ServiceSpecificException. It does not give you:

• Retries. A failed transaction is failed; retrying is your policy.
• Timeouts. A synchronous call waits as long as the server takes.
• Liveness. DeathRecipient tells you the process died, not that it is healthy.
• Streaming. For large data, pass a file descriptor or a shared-memory region and keep the Binder call for control.

The practical consequence is that every AIDL interface is a small distributed system, and the failure modes you would design for in a network client — timeouts, partial failure, version skew — apply here too, just with much lower latency.

How it evolved#

The trajectory is consistent: AIDL started as a tool for app services, gained parcelable support in Android 10, and then became the recommended interface language for HALs, with Android 11 adding stable AIDL for the system/vendor boundary and later releases adding native and Rust backends.²

Under the hood#

• ‹›↗the compiler: parser, backends, versioning
• ‹›IInterface.java↗the base interface every AIDL type extends
• ‹›↗the NDK backend's runtime
• ‹›↗real .aidl HAL definitions to read

Curiosity corner#

• AIDL is older than the HAL use. It shipped for app-to-app bound services long before it was considered for the vendor interface.
• The interface descriptor is a string, and it is checked. It is the only runtime evidence that the two sides were built from the same .aidl file.
• oneway calls are ordered. They are asynchronous, not unordered, which is a distinction that has caused more than one race condition.

Try it#

$ aidl --lang=java -I src -o out src/com/example/tasks/ITaskService.aidl

$ adb shell service list | grep -i hardware | head

Build it#

The builder track's AIDL calculator project walks through writing the .aidl file, implementing the Stub, binding from a client, and observing the generated code. It is the fastest way to make the sequence above concrete. See I01 — AIDL calculator.

Check yourself#

Sources#