AIDL Annotations

AIDL annotations modify how the code generator produces Rust code from .aidl files. They control everything from trait derivation and backing types to nullability and interface stability. This chapter covers the annotations relevant to the Rust backend in rsbinder, with examples showing how each annotation affects the generated code.

If you are new to AIDL data types, read the AIDL Data Types chapter first. Annotations build on those type mappings by adding metadata that changes how types are generated, serialized, or constrained.

@RustDerive

The @RustDerive annotation tells the code generator to add Rust derive attributes to parcelable and union types. Without this annotation, generated types receive only the minimum set of derives needed for serialization.

@RustDerive(Clone=true, PartialEq=true)
parcelable Point {
    int x;
    int y;
}

This generates a Rust struct with both Clone and PartialEq derived:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, PartialEq)]
pub struct Point {
    pub x: i32,
    pub y: i32,
}
}

Available Derives

Why Clone Is Not Derived by Default

Generated types do not derive Clone by default. This is intentional because some AIDL types contain fields that cannot be cloned:

• ParcelFileDescriptor wraps an OwnedFd, which represents sole ownership of a file descriptor. Cloning it would require duplicating the file descriptor at the OS level, which is not a simple bitwise copy.
• ParcelableHolder contains a Mutex, which cannot be cloned.

If your parcelable contains only primitive fields and cloneable types, add @RustDerive(Clone=true) explicitly. If the type contains a ParcelFileDescriptor or ParcelableHolder field, attempting to derive Clone will produce a compile error.

Copy Derivation for Fixed-Size Types

For parcelables that contain only primitive fields, you can derive Copy in addition to Clone. This is typically combined with the @FixedSize annotation:

@RustDerive(Clone=true, Copy=true, PartialEq=true)
@FixedSize
parcelable IntParcelable {
    int value;
}

The Copy derive is only valid when all fields are Copy types. Using it on a parcelable that contains String, arrays, or other heap-allocated types will result in a compile error.

@Backing

The @Backing annotation specifies the underlying integer type for an AIDL enum. This controls both the wire format and the generated Rust type.

@Backing(type="byte")
enum Priority {
    LOW = 0,
    MEDIUM = 1,
    HIGH = 2,
}

The generated Rust code uses a newtype struct wrapping the corresponding integer type, with the enum values exposed as associated constants:

#![allow(unused)]
fn main() {
pub mod Priority {
    #![allow(non_upper_case_globals)]
    // Generated by rsbinder::declare_binder_enum! — produces a
    // newtype struct, not a type alias, so values stay type-safe
    // and the enum carries its full set of derived traits.
    pub struct Priority(pub i8);
    impl Priority {
        pub const LOW: Self = Self(0);
        pub const MEDIUM: Self = Self(1);
        pub const HIGH: Self = Self(2);
    }
}
}

The generated type derives Debug, Default, Copy, Clone, PartialOrd, Ord, PartialEq, Eq, and Hash, and provides an enum_values() associated function returning a [Self; N] of all defined variants. See Enum and Union for the full code-generation details.

Supported Backing Types

If no @Backing annotation is specified, the default backing type is "byte".

Choose the smallest backing type that fits your range of values. Enum values are serialized to the Binder transaction as their backing integer type, so a smaller backing type produces a more compact wire format.

@nullable

The @nullable annotation marks a type as optional, indicating that the value may be absent. In Rust, this maps to Option<T>.

Basic Usage

Apply @nullable to method parameters, return values, or struct fields:

interface IUserService {
    @nullable String getName();
    void setValues(@nullable in int[] values);
}

The generated Rust signatures use Option:

#![allow(unused)]
fn main() {
fn getName(&self) -> rsbinder::status::Result<Option<String>>;
fn setValues(&self, values: Option<&[i32]>) -> rsbinder::status::Result<()>;
}

When None is passed over a Binder transaction, a null marker is written to the parcel. The receiving side deserializes it as None without allocating any data.

Heap-Allocated Nullable: @nullable(heap=true)

AOSP AIDL uses @nullable(heap=true) to mark fields of recursive or self-referential parcelables, so that the C++ and Java backends know to allocate the inner value on the heap:

parcelable RecursiveList {
    int value;
    @nullable(heap=true) RecursiveList next;
}

The Rust backend generates:

#![allow(unused)]
fn main() {
pub struct RecursiveList {
    pub value: i32,
    pub next: Option<Box<RecursiveList>>,
}
}

The Box indirection is necessary because without it, RecursiveList would contain itself directly, making the type infinitely large.

In rsbinder, the Box<T> wrapping is driven by self-reference detection in the code generator, not by the heap=true parameter — the parameter is accepted for AOSP-faithful AIDL syntax compatibility but does not itself control the wrapping. Whenever a parcelable field references the enclosing parcelable's own type, the generator emits Box<...> around it to give the struct a known size. Keep the heap=true form when writing AIDL that must also compile under the AOSP toolchain.

For non-recursive optional fields, plain @nullable is sufficient and avoids the extra heap allocation.

@utf8InCpp

The @utf8InCpp annotation exists in Android AIDL to specify UTF-8 encoding for strings in the C++ backend, where the default encoding is UTF-16. In rsbinder, this annotation has no effect because Rust strings are always UTF-8.

interface ITextService {
    @utf8InCpp String getData();
    @utf8InCpp List<String> getNames();
}

Both String and @utf8InCpp String produce identical Rust type mappings:

You may encounter this annotation in AIDL files that were originally written for Android's C++ backend. It is safe to keep or remove it when targeting rsbinder; the generated Rust code is identical either way.

@Descriptor

The @Descriptor annotation overrides the interface descriptor string that identifies an interface on the Binder wire protocol. This is useful when renaming an interface while maintaining backward compatibility with existing clients or services.

Every Binder interface has a descriptor string derived from its fully qualified name (e.g., android.aidl.tests.IOldName). When you rename an interface, the descriptor changes, breaking compatibility. The @Descriptor annotation lets you decouple the source name from the wire descriptor.

Consider an interface that was originally named IOldName:

// IOldName.aidl
interface IOldName {
    String RealName();
}

You can create a new interface INewName that uses the same descriptor:

// INewName.aidl
@Descriptor(value="android.aidl.tests.IOldName")
interface INewName {
    String RealName();
}

Because both interfaces share the same descriptor, they are interchangeable at the Binder level:

#![allow(unused)]
fn main() {
// A service registered as IOldName can be used as INewName
let new_from_old = old_service
    .as_binder()
    .into_interface::<dyn INewName::INewName>();
assert!(new_from_old.is_ok());
}

This is particularly useful during interface migrations where you want to rename types in your codebase without requiring all clients and services to update simultaneously.

@VintfStability

The @VintfStability annotation marks a type or interface as part of the Vendor Interface (VINTF). VINTF-stable types are subject to stricter compatibility rules to ensure that vendor and system partitions can be updated independently.

@VintfStability
parcelable VintfData {
    int value;
}

Stability Rules

In the upstream Android toolchain, VINTF-stable types are meant to contain only other VINTF-stable types so that their serialization format stays stable across independent system/vendor updates — critical for framework↔HAL compatibility.

rsbinder's generator recognizes @VintfStability and stamps the generated type/interface with Stability::Vintf (so it carries the right stability tier on the wire), but it does not statically or dynamically enforce the "fields must also be VINTF-stable" rule — there is no field-tree validation and no BadValue raised for embedding a non-VINTF type. Treat the constraint as a contract you are responsible for upholding, not one the compiler checks for you.

@FixedSize

The @FixedSize annotation indicates that a parcelable has a fixed serialization size, meaning its wire format is always the same number of bytes regardless of the field values.

@FixedSize
parcelable FixedPoint {
    int x;
    int y;
}

Intended constraints

In upstream Android, a fixed-size parcelable may only contain:

• Primitive types (boolean, byte, char, int, long, float, double)
• Other @FixedSize parcelables
• Enums with a @Backing annotation

and may not contain String/@utf8InCpp String, arrays (T[]), ParcelFileDescriptor, IBinder, or any other variable-length type.

rsbinder note: the generator accepts @FixedSize but currently treats it as a no-op — it neither validates these constraints nor changes the generated layout or wire format. The constraints above are the contract you should follow; rsbinder does not check them for you.

Relationship with @RustDerive(Copy=true)

Copy is derived purely from @RustDerive(Copy=true); @FixedSize is not a prerequisite for it in rsbinder. Conceptually you should still only add Copy to types with a fixed layout, so pairing the two documents intent:

@RustDerive(Clone=true, Copy=true, PartialEq=true)
@FixedSize
parcelable Coordinate {
    double latitude;
    double longitude;
}

@EnforcePermission

@EnforcePermission declares the Android permission(s) a method requires. The generated on_transact arm checks the caller against PermissionManagerService before your handler runs and returns EX_SECURITY if the check fails — so the handler body needs no authorization code:

interface IExample {
    @EnforcePermission("android.permission.INTERNET")
    void doNetworking();

    @EnforcePermission(allOf = {"android.permission.A", "android.permission.B"})
    void needsBoth();

    @EnforcePermission(anyOf = {"android.permission.A", "android.permission.B"})
    void needsEither();
}

The companion documentation-only annotations @PermissionManuallyEnforced and @RequiresNoPermission are recognized and emit no runtime check (they exist so every method can declare its permission posture).

Kernel-only. Android permissions are a kernel-binder concept. Over the RPC transport an @EnforcePermission method is denied (EX_SECURITY) unconditionally — granting would mean granting root to an anonymous peer. For RPC authorization use the transport-native mechanisms, or inject a PermissionAuthority to back the check with your own policy. See Security & Authorization.

Summary

The following table provides a quick reference for all annotations covered in this chapter.

When writing AIDL files for rsbinder, the most commonly used annotations are @RustDerive (for ergonomic Rust types), @Backing (for enums), and @nullable (for optional values). The remaining annotations are important for interoperability with Android or for specific use cases like recursive types and interface migration.