Services and data transfer

This page describes how to register and discover services and how to send data to a service by calling methods defined in interfaces in .hal files.

Register services

HIDL interface servers (objects implementing the interface) can be registered as named services. The registered name need not be related to the interface or package name. If no name is specified, the name "default" is used; this should be used for HALs that don't need to register two implementations of the same interface. For example, the C++ call for service registration defined in each interface is:

status_t status = myFoo->registerAsService();
status_t anotherStatus = anotherFoo->registerAsService("another_foo_service");  // if needed

The version of a HIDL interface is included in the interface itself. It is automatically associated with service registration and can be retrieved via a method call (android::hardware::IInterface::getInterfaceVersion()) on every HIDL interface. Server objects need not be registered and can be passed via HIDL method parameters to another process that makes HIDL method calls into the server.

Discover services

Requests by client code are made for a given interface by name and by version, calling getService on the desired HAL class:

// C++
sp<V1_1::IFooService> service = V1_1::IFooService::getService();
sp<V1_1::IFooService> alternateService = V1_1::IFooService::getService("another_foo_service");
// Java
V1_1.IFooService service = V1_1.IFooService.getService(true /* retry */);
V1_1.IFooService alternateService = V1_1.IFooService.getService("another", true /* retry */);

Each version of a HIDL interface is treated as a separate interface. Thus, IFooService version 1.1 and IFooService version 2.2 can both be registered as "foo_service" and getService("foo_service") on either interface gets the registered service for that interface. This is why, in most cases, no name parameter needs to be supplied for registration or discovery (meaning name "default").

The Vendor Interface Object also plays a part in the transport method of the returned interface. For an interface IFoo in package android.hardware.foo@1.0, the interface returned by IFoo::getService always uses the transport method declared for android.hardware.foo in the device manifest if the entry exists; and if the transport method isn't available, nullptr is returned.

In some cases, it might be necessary to continue immediately even without getting the service. This can happen (for instance) when a client wants to manage service notifications itself or in a diagnostic program (such as atrace) which needs to get all hwservices and retrieve them. In this case, additional APIs are provided such as tryGetService in C++ or getService("instance-name", false) in Java. The legacy API getService provided in Java also must be used with service notifications. Using this API doesn't avoid the race condition where a server registers itself after the client requests it with one of these no-retry APIs.

Service death notifications

Clients who want to be notified when a service dies can receive death notifications delivered by the framework. To receive notifications, the client must:

  1. Subclass the HIDL class/interface hidl_death_recipient (in C++ code, not in HIDL).
  2. Override its serviceDied() method.
  3. Instantiate an object of the hidl_death_recipient subclass.
  4. Call the linkToDeath() method on the service to monitor, passing in the IDeathRecipient's interface object. Note that this method doesn't take ownership of the death recipient or the proxy on which it is called.

A pseudocode example (C++ and Java are similar):

class IMyDeathReceiver : hidl_death_recipient {
  virtual void serviceDied(uint64_t cookie,
                           wp<IBase>& service) override {
    log("RIP service %d!", cookie);  // Cookie should be 42
  }
};
....
IMyDeathReceiver deathReceiver = new IMyDeathReceiver();
m_importantService->linkToDeath(deathReceiver, 42);

The same death recipient can be registered on multiple different services.

Data transfer

Data can be sent to a service by calling methods defined in interfaces in .hal files. There are two kinds of methods:

  • Blocking methods wait until the server has produced a result.
  • Oneway methods send data in only one direction and don't block. If the amount of data in-flight in RPC calls exceeds implementation limits, the calls might either block or return an error indication (behavior is not yet determined).

A method that doesn't return a value but isn't declared as oneway is still blocking.

All methods declared in a HIDL interface are called in a single direction, either from the HAL or into the HAL. The interface doesn't specify which direction it's called in. Architectures that need calls to originate from the HAL should provide two (or more) interfaces in the HAL package and serve the appropriate interface from each process. The words client and server are used with respect to the calling direction of the interface (i.e. the HAL can be a server of one interface and a client of another interface).

Callbacks

The word callback refers to two different concepts, distinguished by synchronous callback and asynchronous callback.

Synchronous callbacks are used in some HIDL methods that return data. A HIDL method that returns more than one value (or returns one value of non-primitive type) returns its results via a callback function. If only one value is returned and it is a primitive type, a callback isn't used and the value is returned from the method. The server implements the HIDL methods and the client implements the callbacks.

Asynchronous callbacks allow the server of a HIDL interface to originate calls. This is done by passing an instance of a second interface through the first interface. The client of the first interface must act as the server of the second. The server of the first interface can call methods on the second interface object. For example, a HAL implementation can send information asynchronously back to the process that is using it by calling methods on an interface object created and served by that process. Methods in interfaces used for asynchronous callback might be blocking (and might return values to the caller) or oneway. For an example, see "Asynchronous callbacks" in HIDL C++.

To simplify memory ownership, method calls and callbacks take only in parameters and don't support out or inout parameters.

Per-transaction limits

Per-transaction limits aren't imposed on the amount of data sent in HIDL methods and callbacks. However, calls exceeding 4KB per transaction are considered excessive. If this is seen, re-architecting the given HIDL interface is recommended. Another limitation is the resources available to the HIDL infrastructure to handle multiple simultaneous transactions. Multiple transactions can be in-flight simultaneously due to multiple threads or processes sending calls to a process or multiple oneway calls that aren't handled quickly by the receiving process. The maximum total space available for all concurrent transactions is 1MB by default.

In a well-designed interface, exceeding these resource limitations shouldn't happen; if it does, the call that exceeded them can either block until resources become available or signal a transport error. Each occurrence of exceeding per-transaction limits or overflowing HIDL implementation resources by aggregate in-flight transactions is logged to facilitate debugging.

Method implementations

HIDL generates header files declaring the necessary types, methods, and callbacks in the target language (C++ or Java). The prototype of HIDL-defined methods and callbacks is the same for both client and server code. The HIDL system provides proxy implementations of the methods on the caller side that organize the data for IPC transport, and stub code on the callee side that passes the data into developer implementations of the methods.

The caller of a function (HIDL method or callback) has ownership of the data structures passed into the function, and retains ownership after the call; in all cases the callee doesn't need to free or release the storage.

  • In C++, the data might be read-only (attempts to write to it can cause a segmentation fault) and are valid for the duration of the call. The client can deep-copy the data to propagate it beyond the call.
  • In Java, the code receives a local copy of the data (a normal Java object), which it might keep and modify or allow to be garbage-collected.

Non-RPC data transfer

HIDL has two ways to transfer data without using an RPC call: shared memory and a Fast Message Queue (FMQ), both supported only in C++.

  • Shared memory. The built-in HIDL type memory is used to pass an object representing shared memory that has been allocated. Can be used in a receiving process to map the shared memory.
  • Fast Message Queue (FMQ). HIDL provides a templated message queue type that implements no-wait message-passing. It doesn't use the kernel or scheduler in passthrough or binderized mode (inter-device communication doesn't have these properties). Typically, the HAL sets up its end of the queue, creating an object that can be passed through RPC via a parameter of built-in HIDL type MQDescriptorSync or MQDescriptorUnsync. This object can be used by the receiving process to set up the other end of the queue.
    • Sync queues aren't allowed to overflow, and can only have one reader.
    • Unsync queues are allowed to overflow, and can have many readers, each of which must read data in time or lose it.
    Neither type is allowed to underflow (read from an empty queue fails), and each type can only have one writer.

For more details on FMQ, see Fast Message Queue (FMQ).