This section describes how to register and discover services and how to send
data to a service by calling methods defined in interfaces in .hal
files.
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 do not 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 will make HIDL method calls
into the server.
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 returned interface by
IFoo::getService
always use the transport method declared for
android.hardware.foo
in the device manifest if the entry exists;
and if the transport method is not available, nullptr is returned.
In some cases, it may 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 does not avoid the race condition where a server
registers itself after the client requests it with one of these no-retry APIs.
Clients who want to be notified when a service dies can receive death notifications delivered by the framework. To receive notifications, the client must:
hidl_death_recipient
(in C++
code, not in HIDL).serviceDied()
method.hidl_death_recipient
subclass.
linkToDeath()
method on the service to monitor,
passing in the IDeathRecipient
's interface object. Note that this
method does not 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 may be registered on multiple different services.
Data may be sent to a service by calling methods defined in interfaces in
.hal
files. There are two kinds of methods:
A method that does not return a value but is not 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 does not specify which direction it will be 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).
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 is not 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 may 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 may be blocking (and may 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 do not support out
or
inout
parameters.
Per-transaction limits are not 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
are not 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 should not happen; if it does, the call which exceeded them may 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.
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 does not need to free or release the storage.
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++.
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.MQDescriptorSync
or MQDescriptorUnsync
. This
object can be used by the receiving process to set up the other end of the queue.
For more details on FMQ, see Fast Message Queue (FMQ).